Commit 6201bcc for stable-diffusion.cpp
commit 6201bcc7ea6d742f0041b1ca169146df5bbc7efc
Author: leejet <leejet714@gmail.com>
Date: Sat Nov 14 19:26:26 2026 +0800
docs: standardize model guides and server documentation
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 5e2a43d..94156c8 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -13,3 +13,4 @@
## Checklist
- [ ] I have read and confirmed this PR follows the [contribution guidelines](https://github.com/leejet/stable-diffusion.cpp/blob/master/CONTRIBUTING.md).
+- [ ] If this PR adds or changes model support, I have added or updated its usage guide and relevant model index/README entries following the [model documentation requirements](https://github.com/leejet/stable-diffusion.cpp/blob/master/CONTRIBUTING.md#model-documentation).
diff --git a/AGENTS.md b/AGENTS.md
index 9579846..ea93c92 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -119,9 +119,13 @@ documentation.
1. Identify the relevant modules under `src/`.
2. Check whether the change touches the public API in `include/`.
3. Consult relevant `docs/` and examples before changing user-facing behavior.
-4. Follow existing local patterns before adding new abstractions.
-5. Keep edits scoped to the requested behavior.
-6. Run the narrowest useful build, test, or inspection command available.
+4. For model or component integrations, read and follow
+ [the model documentation requirements](CONTRIBUTING.md#model-documentation).
+ Add or update the usage guide and relevant index/README entries in the same
+ change. Treat the integration as incomplete until this documentation is included.
+5. Follow existing local patterns before adding new abstractions.
+6. Keep edits scoped to the requested behavior.
+7. Run the narrowest useful build, test, or inspection command available.
Follow `CONTRIBUTING.md` for formatting, naming, PR expectations, dependency
update policy, and security rules. For tokenizer additions, follow its embedded-data
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 42d61e0..1b5cc65 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -43,6 +43,53 @@ Link new documentation from [the documentation index](docs/README.md) or
[the model index](docs/models/README.md), as appropriate. Keep supported model
entries and their guide links in the project README.
+### Model Documentation
+
+Every new model or component integration must include a user guide in
+`docs/models/` in the same PR. For a variant or new task of an existing family,
+update that family's guide instead of creating a duplicate page. Add new guides
+to the model index, and update the supported-model entries and guide links in
+the project README when adding a model family or capability.
+
+Model guides should use the model name as their single top-level heading and
+start with a short description of supported tasks and compatibility requirements.
+`Model files` and `Usage` are required. Use the following sections in order,
+omitting other sections when they have no content:
+
+- `Supported variants` when variants need a separate comparison.
+- `Model files`, with component, weights/downloads, CLI option, and requirement
+ columns. Include tokenizers, projectors, connectors, downloads, conversion, and
+ required preprocessing.
+- `Usage`, with `Web UI` and `CLI` subsections where applicable. Link to the
+ server's shared Web UI guide and list compatible recipes/components. Group
+ complete CLI examples by task or variant within this section; do not add a
+ separate `Quick start` or `Examples` section. Keep API usage in its own
+ subsection when needed.
+- `Options` for model-specific settings.
+- `Notes and limitations` for input/output constraints, memory requirements,
+ and unsupported functionality.
+
+Follow the [model example conventions](docs/models/README.md#example-conventions)
+for working directories and shell syntax. Provide Windows PowerShell and
+Linux/macOS forms of executable examples, using `.\bin\Release\sd-cli.exe` and
+`./bin/sd-cli` respectively from the build directory. Use the corresponding
+server paths for Web UI startup. Keep backend-specific examples clearly labeled.
+Use multiline commands with mode and
+model components first, followed by inputs/prompts, sampling settings, dimensions,
+other model options, memory/backend options, and output/seed settings. Preserve
+checkpoint-specific values when reorganizing existing examples. Keep example
+images next to their commands, and update links when section anchors change.
+Keep shared Web UI operating instructions in `examples/server/README.md` and
+link to them from model guides. Document shared settings by linking to
+`docs/guides/`. Only describe Web UI
+recipes and capabilities that already exist; documentation cleanup alone is not
+a reason to add or change a built-in recipe.
+
+Before submitting, check download links, relative links, command paths, CLI
+options, and any recipe/component mappings against the implementation. Report
+which examples were actually run and which were only inspected in the PR's
+verification notes.
+
Keep tensor layouts, internal class names, kernel implementation details,
algorithm derivations, and development history out of usage guides. Keep task-specific
profiling logs, numerical comparison procedures, and test artifacts local, and
diff --git a/README.md b/README.md
index 224d112..6d62d57 100644
--- a/README.md
+++ b/README.md
@@ -84,7 +84,7 @@ API and command-line option may change frequently.***
- [Boogu Image Edit](./docs/models/boogu_image.md)
- [Mage-Flow-Edit](./docs/models/mage_flow.md#image-editing)
- [LLaDA-Image Edit](./docs/models/llada_image.md#image-editing)
- - [Fibo 2.0 Dev / Edit Turbo](./docs/models/fibo2.md#examples)
+ - [Fibo 2.0 Dev / Edit Turbo](./docs/models/fibo2.md#fibo-20-edit-turbo)
- Video Models
- [Wan2.1/Wan2.2](./docs/models/wan.md)
- [MiniMax-H3](./docs/models/minimax_h3.md)
@@ -136,44 +136,69 @@ API and command-line option may change frequently.***
- Download and extract pre-built binaries from the [releases page](https://github.com/leejet/stable-diffusion.cpp/releases)
- Or build from source by following the [build guide](./docs/build.md)
-Run the commands below from the directory containing `sd-server` and `sd-cli`
-(typically `build/bin/` or `build/bin/Release/` for source builds). On Windows,
-use `.\sd-server.exe` and `.\sd-cli.exe` in place of `./sd-server` and `./sd-cli`.
+The executable examples below run from the build directory (`cd build` from
+the repository root). Windows examples use the Visual Studio Release path;
+adjust the executable path for other build configurations or extracted archives.
+Model files stay under the repository's `models/` directory.
### Download model weights
Choose a model from the [model guides](./docs/models/README.md) and download its
-weights and required components into a `models/` directory. For a simple example,
-download Stable Diffusion v1.5:
+weights and required components. For a simple example, save Stable Diffusion 1.5
+under `models/checkpoints/`:
+
+**Windows (PowerShell)**
+
+```powershell
+New-Item -ItemType Directory -Force ..\models\checkpoints | Out-Null
+curl.exe -L -o ..\models\checkpoints\v1-5-pruned-emaonly.safetensors https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors
+```
+
+**Linux/macOS**
```sh
-mkdir models
-curl -L -o models/v1-5-pruned-emaonly.safetensors https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors
+mkdir -p ../models/checkpoints
+curl -L -o ../models/checkpoints/v1-5-pruned-emaonly.safetensors https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors
```
### Option 1: Web UI
Start the server:
-```sh
-./sd-server --model-dir ./models
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-server.exe --model-dir ..\models
```
-Open <http://127.0.0.1:1234/>, choose the matching model recipe and downloaded
-component files, then click **Load models**. Enter a prompt and generate an image.
+**Linux/macOS**
-For startup scripts, frontend build requirements, and server options, see the
-[server guide](./examples/server/README.md).
+```sh
+./bin/sd-server --model-dir ../models
+```
+
+Open <http://127.0.0.1:1234/>, choose **SD 1.x** in **Recipe**, select the
+checkpoint, and click **Load models**. Enter a prompt and click **Generate**.
+See the [Web UI guide](./examples/server/README.md#web-ui) for the full workflow.
### Option 2: CLI
Generate an image with one command:
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe -m ..\models\checkpoints\v1-5-pruned-emaonly.safetensors -p "a lovely cat"
+```
+
+**Linux/macOS**
+
```sh
-./sd-cli -m ./models/v1-5-pruned-emaonly.safetensors -p "a lovely cat"
+./bin/sd-cli -m ../models/checkpoints/v1-5-pruned-emaonly.safetensors -p "a lovely cat"
```
-Run `./sd-cli --help` for the full list of command-line options. See the
+Run `.\bin\Release\sd-cli.exe --help` on Windows or `./bin/sd-cli --help` on
+Linux/macOS for all command-line options. See the
[CLI guide](./examples/cli/README.md) for additional usage notes.
## Performance
diff --git a/docs/README.md b/docs/README.md
index 45ccdd9..4e998a5 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -42,4 +42,6 @@ For the project overview and supported models, see the [project README](../READM
- [ggml operator extensions](development/ggml_extensions.md)
- [Backend performance probes](development/backend_probe.md)
- [Position embedding cache](development/pe_cache.md)
+- [PuLID implementation and validation](development/pulid.md)
+- [Qwen Image 2.1 prefix cache internals](development/qwen_image_prefix_cache.md)
- [Contribution guidelines](../CONTRIBUTING.md)
diff --git a/docs/development/model_config.md b/docs/development/model_config.md
index d42c322..3982116 100644
--- a/docs/development/model_config.md
+++ b/docs/development/model_config.md
@@ -139,6 +139,9 @@ To add a model:
5. Add version detection signatures and any required weight-name mappings in
`src/model_loader.cpp` and `src/name_conversion.cpp` respectively. Update shared
conditioning or runtime code only when existing behavior cannot serve the model.
+6. Add or update the model's usage guide and relevant index/README entries in the
+ same change, following the
+ [model documentation requirements](../../CONTRIBUTING.md#model-documentation).
Use the existing family integration as the starting point for a variant. For a
new family, `src/model/integrations/moss_image.cpp` is a compact example of a
diff --git a/docs/development/pulid.md b/docs/development/pulid.md
new file mode 100644
index 0000000..b9ed66b
--- /dev/null
+++ b/docs/development/pulid.md
@@ -0,0 +1,46 @@
+# PuLID implementation and validation
+
+For model files, identity preparation, and generation commands, see the
+[PuLID usage guide](../models/pulid.md).
+
+## Architecture summary
+
+The PuLID-Flux contribution to the Flux denoise loop is a stack of 20
+small cross-attention modules (`PerceiverAttentionCA`) inserted between
+the Flux transformer blocks:
+
+- After every 2nd of the 19 double-stream blocks (10 hook points)
+- After every 4th of the 38 single-stream blocks (10 hook points)
+
+Each cross-attention layer takes the current image tokens as query, the
+32-token / 2048-dim identity embedding as key+value, and adds its output
+(scaled by `id_weight`, typically 1.0) back to the image tokens.
+
+## Format (gguf)
+
+The embedding is a standard **gguf** container holding a single tensor:
+
+```
+tensor name : "pulid_id"
+shape : [token_dim, num_tokens] (ggml order; typically [2048, 32])
+type : F16 (also accepts F32 / BF16)
+metadata : general.architecture = "pulid", pulid.version = 1
+```
+
+stable-diffusion.cpp loads it with the normal gguf reader
+(`gguf_init_from_file`) and converts to fp32 at load time -- no bespoke
+parser. Total file size for the typical (32, 2048, fp16) case is ~131 KB.
+
+## Verification
+
+A three-way SHA-256 check is the recommended sanity test when bringing up
+a new combination of model + backend + hardware:
+
+| Run | Expected hash relation |
+|----------------------------------------------|------------------------------------|
+| A: no `--pulid-*` flags | baseline |
+| B: PuLID flags, `--pulid-id-weight 0.0` | **byte-identical to A** |
+| C: PuLID flags, `--pulid-id-weight 1.0` | **different from A,B**, preserves source identity |
+
+If A and C differ but A and B differ too, the injection is allocating
+or computing something even at zero weight -- likely a bug.
diff --git a/docs/development/qwen_image_prefix_cache.md b/docs/development/qwen_image_prefix_cache.md
new file mode 100644
index 0000000..bb5d70c
--- /dev/null
+++ b/docs/development/qwen_image_prefix_cache.md
@@ -0,0 +1,32 @@
+# Qwen Image 2.1 prefix cache
+
+For cache options and memory estimates, see the
+[Qwen Image 2.1 usage guide](../models/qwen_image_2.1.md#prefix-cache).
+
+## Cache behavior
+
+By default, the first denoising call for each fixed condition saves the text and reference-image keys and values from every transformer layer. Later calls only compute the target-image tokens. Positive and negative conditions use separate caches, which are released when sampling ends.
+
+Set `qwen_image_2_1_prefix_cache_type` in `--model-args` to `auto` or a type name using the same parser and case-sensitive names as `--type`:
+
+- `auto` (default): use FP16 only when Flash Attention is enabled, Sage Attention is disabled, the attention scale is unchanged, and every attention operation in the cache-writing or cache-reading graph selects Flash Attention after backend support checks. If an operation falls back, rebuild the prefix in FP32 before executing and keep FP32 for the rest of that sampling run.
+- `f32`: always store FP32 keys and values.
+- `f16`: always store FP16 keys and values, including with ordinary attention or custom attention scaling. This saves cache memory but can introduce additional rounding error.
+- Other types, such as `bf16`, `q4_1`, `q5_0`, `q5_1`, `q8_0`, `q4_K`, `q6_K`, `iq4_nl`, and `iq4_xs`: use the requested storage type if the ggml build provides runtime conversion to and from FP32. Quantization is lossy and must be selected explicitly; `auto` never selects a quantized type.
+
+Cache data is packed into contiguous rows of `hidden_size` elements before conversion, so 256-element quantization blocks work with the model's 128-element attention heads without padding. The type's block size must divide `hidden_size`. Unknown types, types lacking runtime conversion (for example `q8_1` and several IQ formats), and incompatible block sizes are ignored with a warning, leaving the previous setting or the default `auto` unchanged.
+
+For example, use `--model-args qwen_image_2_1_prefix_cache_type=q8_0` to enable 8-bit cache storage. Cached keys and values are converted back to the attention input type before concatenating with the current target tokens. This reduces persistent cache memory; attention working buffers still use floating-point values, and conversion adds work on each step. Backends without the required conversion operations use the existing CPU fallback.
+
+For the default 32-layer model, a prefix of 4096 tokens takes approximately the following memory per condition, excluding weights, working buffers, and allocation overhead:
+
+| Cache type | Memory |
+| --- | ---: |
+| `f32` | 4 GiB |
+| `f16` | 2 GiB |
+| `q8_0` | 1.0625 GiB |
+| `q4_0` | 0.5625 GiB |
+
+The runner accounts for the cache when checking the memory budget. If a cached execution runs out of memory, it releases the prefix caches, disables caching for the rest of that sampling run, and retries the full sequence once. Per-step conditioning extensions currently use the full-sequence path.
+
+Disable this optimization with `--model-args qwen_image_2_1_prefix_cache=false`. It reuses step-independent activations; numerical results can still differ slightly because the matrix sizes change.
diff --git a/docs/guides/edit.md b/docs/guides/edit.md
index a12cc83..942c395 100644
--- a/docs/guides/edit.md
+++ b/docs/guides/edit.md
@@ -19,7 +19,7 @@ Depending on the architecture, different models handle reference images differen
| **Krea2 (Community Edit LoRAs)** | `krea2_ostris_edit` |
| [**Mage-Flow-Edit**](../models/mage_flow.md#image-editing) | `mage_flow` |
| [**LLaDA-Image**](../models/llada_image.md#image-editing) | `llada_image` |
-| [**Fibo 2.0 Dev / Edit Turbo**](../models/fibo2.md#examples) | `fibo2` |
+| [**Fibo 2.0 Dev / Edit Turbo**](../models/fibo2.md#fibo-20-edit-turbo) | `fibo2` |
| **Anima (Community Edit LoRAs)** | `cosmos_reference` |
Stable-diffusion.spp also supports basic Unet-based editing models like instruct-pix2pix or CosXL-Edit. This document is not about those.
diff --git a/docs/guides/sampling.md b/docs/guides/sampling.md
index 499a9f0..7955ce1 100644
--- a/docs/guides/sampling.md
+++ b/docs/guides/sampling.md
@@ -9,13 +9,31 @@ Choose both according to the [model guide](../models/README.md) for your checkpo
For example, using the Stable Diffusion 1.5 checkpoint from the
[quick start](../../README.md#quick-start):
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\v1-5-pruned-emaonly.safetensors `
+ --sampling-method euler_a `
+ --scheduler discrete `
+ --steps 20 `
+ -p "a lovely cat"
+```
+
+**Linux/macOS**
+
```sh
-./sd-cli -m ./models/v1-5-pruned-emaonly.safetensors \
- --sampling-method euler_a --scheduler discrete --steps 20 -p "a lovely cat"
+./bin/sd-cli \
+ -m ../models/checkpoints/v1-5-pruned-emaonly.safetensors \
+ --sampling-method euler_a \
+ --scheduler discrete \
+ --steps 20 \
+ -p "a lovely cat"
```
-Run this from the directory containing `sd-cli`. On Windows, use `sd-cli.exe`
-with your shell's path and line-continuation syntax.
+Run the example from the build directory. See the
+[shared command conventions](../models/README.md#example-conventions) for build
+layouts and platform-specific syntax.
| CLI option | Purpose |
| --- | --- |
@@ -26,8 +44,8 @@ with your shell's path and line-continuation syntax.
| `--sigmas VALUES_OR_PRESET` | Supply a custom schedule instead of generating one with the scheduler. |
| `--hires-sigmas VALUES_OR_PRESET` | Supply a custom schedule for the highres fix second pass. |
-The names below are the exact, case-sensitive CLI values. Run `./sd-cli --help`
-to check the options supported by your installed build.
+The names below are the exact, case-sensitive CLI values. Run `.\bin\Release\sd-cli.exe --help` on Windows or `./bin/sd-cli --help` on
+Linux/macOS to check the options supported by your installed build.
For native server requests, use `sample_params.sample_method` and
`sample_params.scheduler`. See the [server API reference](../../examples/server/api.md)
diff --git a/docs/models/README.md b/docs/models/README.md
index 0f33958..24da05c 100644
--- a/docs/models/README.md
+++ b/docs/models/README.md
@@ -4,6 +4,41 @@ Each guide covers weights, setup, and runnable examples for a model or component
For shared generation options, device configuration, and troubleshooting, see the
[documentation index](../README.md).
+When adding model support, follow the
+[model documentation requirements](../../CONTRIBUTING.md#model-documentation)
+for guide structure, examples, and index updates.
+
+## Example conventions
+
+Run the executable examples from the CMake build directory, for example after
+`cd build` from the repository root. Each guide gives both command forms:
+
+| Platform | CLI path from the build directory | Server path |
+| --- | --- | --- |
+| Windows, Visual Studio Release | `.\bin\Release\sd-cli.exe` | `.\bin\Release\sd-server.exe` |
+| Linux/macOS | `./bin/sd-cli` | `./bin/sd-server` |
+
+Windows examples use PowerShell backticks for line continuation. Linux/macOS
+examples use POSIX shell backslashes. Backend-specific examples identify their
+requirements; Metal examples apply to macOS only. A different CMake generator,
+build configuration, or extracted release archive can use another executable
+location; substitute that path while keeping the arguments.
+
+Keep weights under the repository's `models/` directory, organized into the
+categories described in the server guide. From the build directory these paths
+start with `../models/` on Linux/macOS and `..\models\` on Windows.
+
+Provide input images, masks, audio, or frame directories at the example paths,
+or change the corresponding arguments. Paths under `../inputs/` refer to local
+inputs you supply. Filenames in commands identify the example weights; adjust
+paths to match your downloads. Conversion and preprocessing scripts identify
+when they must be run from the source repository root instead.
+
+The [server Web UI guide](../../examples/server/README.md#web-ui) covers file
+placement, server startup, model loading, inputs, and generation. Each model
+guide lists its compatible recipes and components. Choose files from the same
+variant; a VAE or TAE selection must match that model.
+
## Image generation
- [Anima](anima.md)
@@ -48,7 +83,7 @@ and model presets. Models that support both generation and editing use the same
model guide.
- [Boogu Image Edit](boogu_image.md#boogu-image-edit)
-- [Fibo 2.0 Dev / Edit Turbo](fibo2.md#examples)
+- [Fibo 2.0 Dev / Edit Turbo](fibo2.md#fibo-20-edit-turbo)
- [FLUX.1-Kontext-dev](kontext.md)
- [FLUX.2](flux2.md)
- [FLUX.3 Image](flux3.md)
diff --git a/docs/models/adetailer.md b/docs/models/adetailer.md
index f428318..2072644 100644
--- a/docs/models/adetailer.md
+++ b/docs/models/adetailer.md
@@ -6,13 +6,29 @@ inpaint pass for every detected object. The implementation supports YOLOv8
detection checkpoints. YOLOv8 segmentation and MediaPipe models are not
supported yet.
-## Convert a detector
+## Model files
-Ultralytics checkpoints must be converted before use. The converter fuses
-BatchNorm into convolution layers and writes a safetensors file with the weight
-names expected by the native GGML implementation.
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Base image model | [Compatible image-generation model](README.md) | `-m` / model component options | Required for the inpainting pass |
+| YOLOv8 detector | Converted Safetensors checkpoint prepared below | `--ad-model` | Required; detection checkpoints only |
-```bash
+### Prepare the detector
+
+Run the conversion command from the source repository root, then place the
+converted file at the path used by `--ad-model`.
+
+Ultralytics checkpoints must be converted before use. The converter writes the Safetensors detector used by sd.cpp.
+
+**Windows (PowerShell)**
+
+```powershell
+python scripts\convert_yolov8_to_safetensors.py face_yolov8n.pt face_yolov8n.safetensors
+```
+
+**Linux/macOS**
+
+```sh
python scripts/convert_yolov8_to_safetensors.py face_yolov8n.pt face_yolov8n.safetensors
```
@@ -22,17 +38,44 @@ Only YOLOv8 detection checkpoints are accepted.
PyTorch checkpoints use pickle internally, so only convert `.pt` files from a
trusted source.
-## Repair an existing image
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### CLI
+
+#### Repair an existing image
Use the dedicated `adetailer` mode to detect and repair objects in an existing
image:
-```bash
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M adetailer `
+ -m ..\models\checkpoints\model.safetensors `
+ --ad-model ..\models\detectors\face_yolov8n.safetensors `
+ -i input.png `
+ -p "detailed portrait photo" `
+ --negative-prompt "deformed face" `
+ --steps 24 `
+ --cfg-scale 6 `
+ --strength 0.4 `
+ --sampling-method dpm++2m `
+ --scheduler karras `
+ --extra-ad-args "confidence=0.3,inpaint_padding=32,mask_blur=4" `
+ -o repaired.png
+```
+
+**Linux/macOS**
+
+```sh
./bin/sd-cli \
-M adetailer \
- -m model.safetensors \
+ -m ../models/checkpoints/model.safetensors \
+ --ad-model ../models/detectors/face_yolov8n.safetensors \
-i input.png \
- -o repaired.png \
-p "detailed portrait photo" \
--negative-prompt "deformed face" \
--steps 24 \
@@ -40,8 +83,8 @@ image:
--strength 0.4 \
--sampling-method dpm++2m \
--scheduler karras \
- --ad-model face_yolov8n.safetensors \
- --extra-ad-args "confidence=0.3,inpaint_padding=32,mask_blur=4"
+ --extra-ad-args confidence=0.3,inpaint_padding=32,mask_blur=4 \
+ -o repaired.png
```
This mode reuses the normal image-generation options for the detail pass:
@@ -55,18 +98,32 @@ This mode reuses the normal image-generation options for the detail pass:
Values provided in `--extra-ad-args`, such as `steps`, `cfg_scale`,
`denoising_strength`, or `inpaint_width`, take precedence over inherited values.
-## Repair generated images
+#### Repair generated images
ADetailer can also run automatically after normal image generation:
-```bash
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\model.safetensors `
+ --ad-model ..\models\detectors\face_yolov8n.safetensors `
+ -p "portrait photo" `
+ --ad-prompt "[PROMPT], detailed face" `
+ --ad-negative-prompt "" `
+ --extra-ad-args "confidence=0.3,denoising_strength=0.4,inpaint_width=512,inpaint_height=512"
+```
+
+**Linux/macOS**
+
+```sh
./bin/sd-cli \
- -m model.safetensors \
+ -m ../models/checkpoints/model.safetensors \
+ --ad-model ../models/detectors/face_yolov8n.safetensors \
-p "portrait photo" \
- --ad-model face_yolov8n.safetensors \
--ad-prompt "[PROMPT], detailed face" \
--ad-negative-prompt "" \
- --extra-ad-args "confidence=0.3,denoising_strength=0.4,inpaint_width=512,inpaint_height=512"
+ --extra-ad-args confidence=0.3,denoising_strength=0.4,inpaint_width=512,inpaint_height=512
```
The same options can be supplied when starting `sd-server`. When `--ad-model` is set, its detector runs after OpenAI-compatible and native asynchronous image generation. SDAPI requests enable ADetailer through `alwayson_scripts`, as described below. If no object is detected, the original image is returned unchanged. RGBA output keeps its original alpha channel, including when detected regions are repaired. Detector initialization or detail-pass failures are reported as request failures.
@@ -99,6 +156,8 @@ Supported settings include prompts, confidence, mask filtering by area or confid
Model/VAE switching, non-default noise multipliers, face restoration, ControlNet, and skipping the initial img2img pass are not supported; active requests for these features return an error. Unknown settings and invalid active values also return errors. During detailing, `/sdapi/v1/progress` remains active with an `adetailer` job; its percentage and preview stay fixed until detailing finishes.
+## Options
+
An empty ADetailer prompt inherits the main prompt. `[PROMPT]` inserts the main
prompt, `[SEP]` assigns different prompts to consecutive masks, and `[SKIP]`
skips the corresponding mask.
@@ -138,6 +197,19 @@ for the next mask, and the seed is incremented by the mask index. Use
The detector uses the `detector` backend module. For example, keep detection on
the CPU while diffusion runs on CUDA:
-```bash
+**Windows (PowerShell) arguments**
+
+```text
--backend "diffusion=cuda0,detector=cpu"
```
+
+**Linux/macOS arguments**
+
+```text
+--backend diffusion=cuda0,detector=cpu
+```
+
+## Notes and limitations
+
+YOLOv8 segmentation and MediaPipe detectors are not supported. See the
+[server API reference](../../examples/server/api.md) for request schemas.
diff --git a/docs/models/anima.md b/docs/models/anima.md
index cebe378..38f19f6 100644
--- a/docs/models/anima.md
+++ b/docs/models/anima.md
@@ -1,21 +1,62 @@
-# How to Use
+# Anima
-## Download weights
+Anima generates images from text using a Qwen3 text encoder and a compatible Qwen Image VAE.
-- Download Anima
- - safetensors: https://huggingface.co/circlestone-labs/Anima/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/Bedovyy/Anima-GGUF/tree/main
- - gguf Anima2: https://huggingface.co/JusteLeo/Anima2-GGUF/tree/main
-- Download vae
- - safetensors: https://huggingface.co/circlestone-labs/Anima/tree/main/split_files/vae
-- Download Qwen3-0.6B-Base
- - safetensors: https://huggingface.co/circlestone-labs/Anima/tree/main/split_files/text_encoders
- - gguf: https://huggingface.co/mradermacher/Qwen3-0.6B-Base-GGUF/tree/main
+## Model files
-## Examples
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Anima | [Safetensors](https://huggingface.co/circlestone-labs/Anima/tree/main/split_files/diffusion_models)<br>[GGUF](https://huggingface.co/Bedovyy/Anima-GGUF/tree/main)<br>gguf Anima2: [GGUF](https://huggingface.co/JusteLeo/Anima2-GGUF/tree/main) | `--diffusion-model` | Required |
+| vae | [Safetensors](https://huggingface.co/circlestone-labs/Anima/tree/main/split_files/vae) | `--vae` | Use matching VAE |
+| Qwen3-0.6B-Base | [Safetensors](https://huggingface.co/circlestone-labs/Anima/tree/main/split_files/text_encoders)<br>[GGUF](https://huggingface.co/mradermacher/Qwen3-0.6B-Base-GGUF/tree/main) | `--llm` | Use matching text encoder |
+
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Anima (`anima`) | `diffusion_model`, `llm`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\anima-preview.safetensors `
+ --vae ..\models\vae\qwen_image_vae.safetensors `
+ --llm ..\models\text_encoders\qwen_3_06b_base.safetensors `
+ -p "a lovely cat holding a sign says 'anima.cpp'" `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ --offload-to-cpu `
+ -v
+```
+
+**Linux/macOS**
```sh
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\anima-preview.safetensors --vae ..\models\vae\qwen_image_vae.safetensors --llm ..\models\text_encoders\qwen_3_06b_base.safetensors -p "a lovely cat holding a sign says 'anima.cpp'" --cfg-scale 6.0 --sampling-method euler -v --offload-to-cpu
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/anima-preview.safetensors \
+ --vae ../models/vae/qwen_image_vae.safetensors \
+ --llm ../models/text_encoders/qwen_3_06b_base.safetensors \
+ -p "a lovely cat holding a sign says 'anima.cpp'" \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ --offload-to-cpu \
+ -v
```
<img alt="anima image example" src="../../assets/anima/example.png" />
diff --git a/docs/models/animatediff.md b/docs/models/animatediff.md
index 2486fb4..ef110fe 100644
--- a/docs/models/animatediff.md
+++ b/docs/models/animatediff.md
@@ -1,14 +1,34 @@
-# AnimateDiff (SD 1.5)
+# AnimateDiff
-AnimateDiff adds motion to a frozen Stable Diffusion 1.5 checkpoint by
-injecting a temporal-attention module at 20 UNet slots. The base SD 1.5
-model, VAE, and text encoder are unchanged; only the motion module produces
-the temporal residual that turns a batch of independent frames into a
-coherent animation. Reference: Guo et al., "AnimateDiff: Animate Your
-Personalized Text-to-Image Diffusion Models without Specific Tuning"
-(https://arxiv.org/abs/2307.04725).
+AnimateDiff adds video generation to an SD 1.5 checkpoint using a compatible motion module.
-## Download weights
+Use the SD 1.5 checkpoint for the desired characters and style, and choose the
+motion module and resolution below. See the
+[AnimateDiff paper](https://arxiv.org/abs/2307.04725) for the model reference.
+
+## Supported variants
+
+Per [animatediff.net/models](https://animatediff.net/models):
+
+| Module | Base | Native res | Character |
+|---------------------|------|------------|-----------|
+| `mm_sd_v14.ckpt` | 1.5 | 256x256 | earliest, more jittery |
+| `mm_sd_v15.ckpt` | 1.5 | 256x256 | improved stability over v1.4 |
+| `mm_sd_v15_v2.ckpt` | 1.5 | 384x384 | significantly better motion dynamics |
+| `v3_sd15_mm.ckpt` | 1.5 | 512x512 | smoothest, highest quality; pairs with a Domain Adapter LoRA |
+| `mm_sdxl_v10_beta` | SDXL | 512x512 | experimental, not yet supported here |
+
+Match your `-H -W` to the module's native resolution for best results. v3 is
+trained at 512x512 - going smaller (e.g. 384x384) still works but the motion
+character is closer to v2.
+
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| SD 1.5 checkpoint | [Compatible SD 1.5 checkpoint](sd.md) | `-m` / `--model` | Required; SDXL motion modules are not supported |
+| Motion module | v1/v2/v3 motion weights listed below | `--motion-module` | Required; match the resolution and version |
+| Domain adapter LoRA | v3 adapter listed below | `--lora-model-dir` and prompt | Optional; v3 only |
- Motion module (v3, recommended)
- fp16 safetensors: https://huggingface.co/conrevo/AnimateDiff-A1111/resolve/main/motion_module/mm_sd15_v3.safetensors
@@ -25,75 +45,173 @@ Personalized Text-to-Image Diffusion Models without Specific Tuning"
The motion module is `~836 MB` and loads alongside the SD 1.5 UNet via
`--motion-module`.
-## Motion module versions
+## Usage
-Per [animatediff.net/models](https://animatediff.net/models):
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
-| Module | Base | Native res | Character |
-|---------------------|------|------------|-----------|
-| `mm_sd_v14.ckpt` | 1.5 | 256x256 | earliest, more jittery |
-| `mm_sd_v15.ckpt` | 1.5 | 256x256 | improved stability over v1.4 |
-| `mm_sd_v15_v2.ckpt` | 1.5 | 384x384 | significantly better motion dynamics |
-| `v3_sd15_mm.ckpt` | 1.5 | 512x512 | smoothest, highest quality; pairs with a Domain Adapter LoRA |
-| `mm_sdxl_v10_beta` | SDXL | 512x512 | experimental, not yet supported here |
+### Web UI
-Match your `-H -W` to the module's native resolution for best results. v3 is
-trained at 512x512 - going smaller (e.g. 384x384) still works but the motion
-character is closer to v2.
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| AnimateDiff SD 1.5 (`animatediff-sd15`) | `model`, `motion_module`, `vae`, `tae` |
-## Examples
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Text-to-video
Generate an 8-frame animation at 512x512, seed 42, 20 steps. The sampler /
scheduler / CFG values below match what mm_sd15_v3 was trained with; using
SD 1.5 defaults (euler_a, low CFG) produces noise-like output.
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --model ..\models\checkpoints\realisticVisionV60B1.safetensors `
+ --motion-module ..\models\motion_modules\animatediff\mm_sd15_v3.safetensors `
+ -p "a red apple on a wooden table" `
+ --cfg-scale 8.0 `
+ --sampling-method euler `
+ --scheduler discrete `
+ --steps 20 `
+ -H 512 `
+ -W 512 `
+ --video-frames 8 `
+ --fps 8 `
+ --offload-to-cpu `
+ -s 42 `
+ -o out.avi
```
-.\bin\Release\sd-cli.exe -M vid_gen \
- --model ..\models\checkpoints\realisticVisionV60B1.safetensors \
- --motion-module ..\models\animatediff\mm_sd15_v3.safetensors \
- --offload-to-cpu \
- -p "a red apple on a wooden table" \
- --cfg-scale 8.0 --sampling-method euler --scheduler discrete \
- -H 512 -W 512 --video-frames 8 --fps 8 --steps 20 -s 42 \
- -o out.avi
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --model ../models/checkpoints/realisticVisionV60B1.safetensors \
+ --motion-module ../models/motion_modules/animatediff/mm_sd15_v3.safetensors \
+ -p "a red apple on a wooden table" \
+ --cfg-scale 8.0 \
+ --sampling-method euler \
+ --scheduler discrete \
+ --steps 20 \
+ -H 512 \
+ -W 512 \
+ --video-frames 8 \
+ --fps 8 \
+ --offload-to-cpu \
+ -s 42 \
+ -o out.avi
```
Generate at the motion module's native 16-frame context (recommended for
best temporal quality). Needs more VRAM at 512x512, so drop to 384x384 or
use layer streaming:
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --model ..\models\checkpoints\realisticVisionV60B1.safetensors `
+ --motion-module ..\models\motion_modules\animatediff\mm_sd15_v3.safetensors `
+ -p "photo of coastline, rocks, storm weather, wind, waves, lightning" `
+ --cfg-scale 8.0 `
+ --sampling-method euler `
+ --scheduler discrete `
+ --steps 20 `
+ -H 384 `
+ -W 384 `
+ --video-frames 16 `
+ --fps 8 `
+ --offload-to-cpu `
+ -s 42 `
+ -o out.avi
```
-.\bin\Release\sd-cli.exe -M vid_gen \
- --model ..\models\checkpoints\realisticVisionV60B1.safetensors \
- --motion-module ..\models\animatediff\mm_sd15_v3.safetensors \
- --offload-to-cpu \
- -p "photo of coastline, rocks, storm weather, wind, waves, lightning" \
- --cfg-scale 8.0 --sampling-method euler --scheduler discrete \
- -H 384 -W 384 --video-frames 16 --fps 8 --steps 20 -s 42 \
- -o out.avi
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --model ../models/checkpoints/realisticVisionV60B1.safetensors \
+ --motion-module ../models/motion_modules/animatediff/mm_sd15_v3.safetensors \
+ -p "photo of coastline, rocks, storm weather, wind, waves, lightning" \
+ --cfg-scale 8.0 \
+ --sampling-method euler \
+ --scheduler discrete \
+ --steps 20 \
+ -H 384 \
+ -W 384 \
+ --video-frames 16 \
+ --fps 8 \
+ --offload-to-cpu \
+ -s 42 \
+ -o out.avi
```
Low-VRAM streaming (verified with a 2 GiB cap on RTX 3060):
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --model ..\models\checkpoints\realisticVisionV60B1.safetensors `
+ --motion-module ..\models\motion_modules\animatediff\mm_sd15_v3.safetensors `
+ -p "photo of coastline, rocks, storm weather, wind, waves, lightning" `
+ --cfg-scale 8.0 `
+ --sampling-method euler `
+ --scheduler discrete `
+ --steps 20 `
+ -H 384 `
+ -W 384 `
+ --video-frames 8 `
+ --fps 8 `
+ --max-vram 2.0 `
+ -s 42 `
+ -o out.avi
```
-.\bin\Release\sd-cli.exe -M vid_gen \
- --model ..\models\checkpoints\realisticVisionV60B1.safetensors \
- --motion-module ..\models\animatediff\mm_sd15_v3.safetensors \
- --max-vram 2.0 \
- -p "photo of coastline, rocks, storm weather, wind, waves, lightning" \
- --cfg-scale 8.0 --sampling-method euler --scheduler discrete \
- -H 384 -W 384 --video-frames 8 --fps 8 --steps 20 -s 42 \
- -o out.avi
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --model ../models/checkpoints/realisticVisionV60B1.safetensors \
+ --motion-module ../models/motion_modules/animatediff/mm_sd15_v3.safetensors \
+ -p "photo of coastline, rocks, storm weather, wind, waves, lightning" \
+ --cfg-scale 8.0 \
+ --sampling-method euler \
+ --scheduler discrete \
+ --steps 20 \
+ -H 384 \
+ -W 384 \
+ --video-frames 8 \
+ --fps 8 \
+ --max-vram 2.0 \
+ -s 42 \
+ -o out.avi
```
-## Reference-quality reproduction
+#### Reference-quality reproduction
Using guoyww's official reference configs on this impl (RealisticVision v6.0
base + `mm_sd15_v3` or `mm_sd_v15_v2` + native resolution + 16 frames + euler
+ 25 steps + CFG 8 + linear beta schedule) reproduces the reference
AnimateDiff output style.
-### v3 (512x512, `mm_sd15_v3`)
+##### v3 (512x512, `mm_sd15_v3`)
| Prompt | Sample |
|---------------------------------------|--------|
@@ -102,7 +220,7 @@ AnimateDiff output style.
| Coastline, storm, waves, lightning | <img src="../../assets/animatediff/v3_coast.gif" width="256"/> |
| Old house, storm, forest, night | <img src="../../assets/animatediff/v3_house.gif" width="256"/> |
-### v2 (384x384, `mm_sd_v15_v2.ckpt`)
+##### v2 (384x384, `mm_sd_v15_v2.ckpt`)
| Prompt | Sample |
|---------------------------------------|--------|
@@ -116,7 +234,7 @@ and subtle for static subjects (close-up macro), matching reference behavior.
v2 has an additional motion module at the UNet middle block that v3 dropped;
this impl auto-detects the topology from the checkpoint.
-### v3 + Domain Adapter LoRA
+##### v3 + Domain Adapter LoRA
Attaching the `v3_sd15_adapter` LoRA sharpens the base UNet output toward
the training distribution the motion module was fine-tuned against. Same
@@ -127,14 +245,29 @@ prompt, seed, config as above:
Individual fur strands, glowing inner-ear, and richer forest detail become
visible compared to the no-LoRA rendering.
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --model ..\models\checkpoints\realisticVisionV60B1.safetensors `
+ --motion-module ..\models\motion_modules\mm_sd15_v3.safetensors `
+ --lora-model-dir .\loras `
+ -p "close up photo of a rabbit ...<lora:v3_sd15_adapter:1.0>" ...
```
-sd-cli -M vid_gen --model realisticVisionV60B1.safetensors \
- --motion-module mm_sd15_v3.safetensors \
- --lora-model-dir ./loras \
- -p "close up photo of a rabbit ...<lora:v3_sd15_adapter:1.0>" ...
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --model ../models/checkpoints/realisticVisionV60B1.safetensors \
+ --motion-module ../models/motion_modules/mm_sd15_v3.safetensors \
+ --lora-model-dir ./loras \
+ -p "close up photo of a rabbit ...<lora:v3_sd15_adapter:1.0>" ...
```
-## img2video
+#### img2video
Pass a pre-rendered image via `-i / --init-img` to animate FROM it. All N output frames start from the encoded init latent, then per-frame noise is added at `--strength`. Character identity, composition, and quality are anchored by the init image; the motion module adds subtle motion on top.
@@ -142,18 +275,55 @@ Left: init image rendered with `-M img_gen`. Right: 8-frame vid_gen output.
<img src="../../assets/animatediff/img2video_demo.gif" width="512"/>
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M img_gen ... `
+ -o init.png "#" any high-quality still
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --motion-module ..\models\motion_modules\mm_sd15_v3.safetensors `
+ -i init.png `
+ -p ... `
+ --strength 0.75 `
+ --cfg-scale 7.0 `
+ --sampling-method euler `
+ --scheduler karras `
+ --steps 25 `
+ -H 512 `
+ -W 512 `
+ --video-frames 8 `
+ -s 42 `
+ -o out.avi
```
-sd-cli -M img_gen ... -o init.png # any high-quality still
-sd-cli -M vid_gen --motion-module mm_sd15_v3.safetensors \
- -i init.png --strength 0.75 \
- --cfg-scale 7.0 --sampling-method euler --scheduler karras \
- -H 512 -W 512 --video-frames 8 --steps 25 -s 42 \
- -p "..." -o out.avi
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M img_gen ... \
+ -o init.png "#" any high-quality still
+./bin/sd-cli \
+ -M vid_gen \
+ --motion-module ../models/motion_modules/mm_sd15_v3.safetensors \
+ -i init.png \
+ -p ... \
+ --strength 0.75 \
+ --cfg-scale 7.0 \
+ --sampling-method euler \
+ --scheduler karras \
+ --steps 25 \
+ -H 512 \
+ -W 512 \
+ --video-frames 8 \
+ -s 42 \
+ -o out.avi
```
`--strength` controls how far the motion module is allowed to deviate from the init image (higher = more motion, lower = more static).
-## Notes
+## Notes and limitations
- The motion module was trained at `video_length=16`. Running with
`--video-frames 16` gives the best coherence; F=8 works but shows a shorter
diff --git a/docs/models/boogu_image.md b/docs/models/boogu_image.md
index 2a54f4b..d7d133c 100644
--- a/docs/models/boogu_image.md
+++ b/docs/models/boogu_image.md
@@ -1,31 +1,93 @@
-# How to Use
+# Boogu Image
Boogu Image uses a Boogu diffusion transformer, the FLUX VAE, and Qwen3-VL as the LLM text and vision encoder.
-## Download weights
+## Model files
-- Download Boogu Image
- - safetensors: https://huggingface.co/Comfy-Org/Boogu-Image/tree/main/diffusion_models
-- Download vae
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.1-dev/blob/main/ae.safetensors
-- Download Qwen3-VL 8B
- - gguf: https://huggingface.co/unsloth/Qwen3-VL-8B-Instruct-GGUF/tree/main
- - For image editing with GGUF text encoders, also download the matching mmproj file and pass it with `--llm_vision`.
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Boogu Image | [Safetensors](https://huggingface.co/Comfy-Org/Boogu-Image/tree/main/diffusion_models) | `--diffusion-model` | Required |
+| vae | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.1-dev/blob/main/ae.safetensors) | `--vae` | Use matching VAE |
+| Qwen3-VL 8B | [GGUF](https://huggingface.co/unsloth/Qwen3-VL-8B-Instruct-GGUF/tree/main)<br>For image editing with GGUF text encoders, also download the matching mmproj file and pass it with `--llm_vision`. | `--llm` | Use matching text encoder |
-## Examples
+## Usage
-### Boogu Image Base
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Boogu Image Base (`boogu-image`) | `diffusion_model`, `llm`, `vae`, `tae` |
+| Boogu Image Edit (`boogu-image-edit`) | `diffusion_model`, `llm`, `llm_vision`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Boogu Image Base
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\boogu_image_base_bf16.safetensors `
+ --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf `
+ --vae ..\models\vae\ae.sft `
+ -p "a lovely cat" `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\boogu_image_base_bf16.safetensors --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf --vae ..\models\vae\ae.sft -p "a lovely cat" -v --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/boogu_image_base_bf16.safetensors \
+ --llm ../models/text_encoders/Qwen3VL-8B-Instruct-Q4_K_M.gguf \
+ --vae ../models/vae/ae.sft \
+ -p "a lovely cat" \
+ --offload-to-cpu \
+ -v
```
<img width="256" alt="Boogu Image Base example" src="../../assets/boogu/example.png" />
-### Boogu Image Edit
+#### Boogu Image Edit
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\boogu_image_edit_bf16.safetensors `
+ --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf `
+ --llm_vision ..\models\text_encoders\mmproj-Qwen3VL-8B-Instruct-F16.gguf `
+ --vae ..\models\vae\ae.sft `
+ -r ..\inputs\flux\flux1-dev-q8_0.png `
+ -p "change 'flux.cpp' to 'boogu.cpp'" `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\boogu_image_edit_bf16.safetensors --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf --llm_vision ..\models\text_encoders\mmproj-Qwen3VL-8B-Instruct-F16.gguf --vae ..\models\vae\ae.sft -v --offload-to-cpu -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'boogu.cpp'"
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/boogu_image_edit_bf16.safetensors \
+ --llm ../models/text_encoders/Qwen3VL-8B-Instruct-Q4_K_M.gguf \
+ --llm_vision ../models/text_encoders/mmproj-Qwen3VL-8B-Instruct-F16.gguf \
+ --vae ../models/vae/ae.sft \
+ -r ../inputs/flux/flux1-dev-q8_0.png \
+ -p "change 'flux.cpp' to 'boogu.cpp'" \
+ --offload-to-cpu \
+ -v
```
-<img width="256" alt="Boogu Image Edit example" src="../../assets/boogu/edit_example.png" />
\ No newline at end of file
+<img width="256" alt="Boogu Image Edit example" src="../../assets/boogu/edit_example.png" />
diff --git a/docs/models/chroma.md b/docs/models/chroma.md
index ccf63c6..51c9685 100644
--- a/docs/models/chroma.md
+++ b/docs/models/chroma.md
@@ -1,32 +1,101 @@
-# How to Use
+# Chroma
+
+Chroma generates images from text using T5-XXL and the FLUX.1 VAE.
You can run Chroma using stable-diffusion.cpp with a GPU that has 6GB or even 4GB of VRAM, without needing to offload to RAM.
-## Download weights
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Chroma | If you don't want to do the conversion yourself, download the preconverted gguf model from [silveroxides/Chroma-GGUF](https://huggingface.co/silveroxides/Chroma-GGUF)<br>Otherwise, download chroma's safetensors from [lodestones/Chroma](https://huggingface.co/lodestones/Chroma) | `--diffusion-model` | Required |
+| vae | vae from [Download](https://huggingface.co/black-forest-labs/FLUX.1-dev/blob/main/ae.safetensors) | `--vae` | Use matching VAE |
+| t5xxl | t5xxl from [Download](https://huggingface.co/comfyanonymous/flux_text_encoders/blob/main/t5xxl_fp16.safetensors) | `--t5xxl` | Required |
+
+### Optional conversion
-- Download Chroma
- - If you don't want to do the conversion yourself, download the preconverted gguf model from [silveroxides/Chroma-GGUF](https://huggingface.co/silveroxides/Chroma-GGUF)
- - Otherwise, download chroma's safetensors from [lodestones/Chroma](https://huggingface.co/lodestones/Chroma)
-- Download vae from https://huggingface.co/black-forest-labs/FLUX.1-dev/blob/main/ae.safetensors
-- Download t5xxl from https://huggingface.co/comfyanonymous/flux_text_encoders/blob/main/t5xxl_fp16.safetensors
+Run executable conversion examples from the build directory using the
+[shared path and shell conventions](README.md#example-conventions).
-## Convert Chroma weights
+#### Convert Chroma weights
You can download the preconverted gguf weights from [silveroxides/Chroma-GGUF](https://huggingface.co/silveroxides/Chroma-GGUF), this way you don't have to do the conversion yourself.
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M convert `
+ -m ..\models\unet\chroma-unlocked-v40.safetensors `
+ --type q8_0 `
+ -o ..\models\diffusion_models\chroma-unlocked-v40-q8_0.gguf `
+ -v
```
-.\bin\Release\sd-cli.exe -M convert -m ..\models\unet\chroma-unlocked-v40.safetensors -o ..\models\chroma-unlocked-v40-q8_0.gguf -v --type q8_0
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M convert \
+ -m ../models/unet/chroma-unlocked-v40.safetensors \
+ --type q8_0 \
+ -o ../models/diffusion_models/chroma-unlocked-v40-q8_0.gguf \
+ -v
```
-## Run
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Chroma (`chroma`) | `diffusion_model`, `t5xxl`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Example
-### Example
For example:
-```
- .\bin\Release\sd-cli.exe --diffusion-model ..\models\chroma-unlocked-v40-q8_0.gguf --vae ..\models\ae.sft --t5xxl ..\models\t5xxl_fp16.safetensors -p "a lovely cat holding a sign says 'chroma.cpp'" --cfg-scale 4.0 --sampling-method euler -v --model-args chroma_use_dit_mask=false --clip-on-cpu
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\chroma-unlocked-v40-q8_0.gguf `
+ --vae ..\models\vae\ae.sft `
+ --t5xxl ..\models\text_encoders\t5xxl_fp16.safetensors `
+ --model-args chroma_use_dit_mask=false `
+ -p "a lovely cat holding a sign says 'chroma.cpp'" `
+ --cfg-scale 4.0 `
+ --sampling-method euler `
+ --clip-on-cpu `
+ -v
```
-
+**Linux/macOS**
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/chroma-unlocked-v40-q8_0.gguf \
+ --vae ../models/vae/ae.sft \
+ --t5xxl ../models/text_encoders/t5xxl_fp16.safetensors \
+ --model-args chroma_use_dit_mask=false \
+ -p "a lovely cat holding a sign says 'chroma.cpp'" \
+ --cfg-scale 4.0 \
+ --sampling-method euler \
+ --clip-on-cpu \
+ -v
+```
+
diff --git a/docs/models/chroma_radiance.md b/docs/models/chroma_radiance.md
index 892db78..dbb8ad5 100644
--- a/docs/models/chroma_radiance.md
+++ b/docs/models/chroma_radiance.md
@@ -1,21 +1,57 @@
-# How to Use
+# Chroma1-Radiance
-## Download weights
+Chroma1-Radiance generates images directly in pixel space using T5-XXL. No VAE is required.
-- Download Chroma1-Radiance
- - safetensors: https://huggingface.co/lodestones/Chroma1-Radiance/tree/main
- - gguf: https://huggingface.co/silveroxides/Chroma1-Radiance-GGUF/tree/main
+## Model files
-- Download t5xxl
- - safetensors: https://huggingface.co/comfyanonymous/flux_text_encoders/blob/main/t5xxl_fp16.safetensors
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Chroma1-Radiance | [Safetensors](https://huggingface.co/lodestones/Chroma1-Radiance/tree/main)<br>[GGUF](https://huggingface.co/silveroxides/Chroma1-Radiance-GGUF/tree/main) | `--diffusion-model` | Required |
+| t5xxl | [Safetensors](https://huggingface.co/comfyanonymous/flux_text_encoders/blob/main/t5xxl_fp16.safetensors) | `--t5xxl` | Required |
-## Examples
+## Usage
-```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\Chroma1-Radiance-v0.4-Q8_0.gguf --t5xxl ..\models\clip\t5xxl_fp16.safetensors -p "a lovely cat holding a sign says 'chroma radiance cpp'" --cfg-scale 4.0 --sampling-method euler -v
-```
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
-<img alt="Chroma1-Radiance" src="../../assets/flux/chroma1-radiance.png" />
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Chroma Radiance (`chroma-radiance`) | `diffusion_model`, `t5xxl` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+### CLI
+**Windows (PowerShell)**
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\Chroma1-Radiance-v0.4-Q8_0.gguf `
+ --t5xxl ..\models\text_encoders\clip\t5xxl_fp16.safetensors `
+ -p "a lovely cat holding a sign says 'chroma radiance cpp'" `
+ --cfg-scale 4.0 `
+ --sampling-method euler `
+ -v
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/Chroma1-Radiance-v0.4-Q8_0.gguf \
+ --t5xxl ../models/text_encoders/clip/t5xxl_fp16.safetensors \
+ -p "a lovely cat holding a sign says 'chroma radiance cpp'" \
+ --cfg-scale 4.0 \
+ --sampling-method euler \
+ -v
+```
+
+<img alt="Chroma1-Radiance" src="../../assets/flux/chroma1-radiance.png" />
diff --git a/docs/models/distilled_sd.md b/docs/models/distilled_sd.md
index 7aa8fbe..30e75aa 100644
--- a/docs/models/distilled_sd.md
+++ b/docs/models/distilled_sd.md
@@ -1,11 +1,18 @@
-# Running distilled models: SSD1B, Vega and SDx.x with tiny U-Nets
+# Distilled Stable Diffusion models
-## Preface
+This guide covers SSD-1B, Vega, Tiny SD/SD2, and SDXS checkpoints. Choose the
+base-model family and preparation steps matching the checkpoint.
-These models feature a reduced U-Net architecture. Unlike standard SDXL models, the SSD-1B and Vega U-Net contains only one middle block and fewer attention layers in its up- and down-blocks, resulting in significantly smaller file sizes. Using these models can reduce inference time by more than 33%. For more details, refer to Segmind's paper: https://arxiv.org/abs/2401.02677v1.
-Similarly, SD1.x- and SD2.x-style models with a tiny U-Net consist of only 6 U-Net blocks, leading to very small files and time savings of up to 50%. For more information, see the paper: https://arxiv.org/pdf/2305.15798.pdf.
+## Model files
-## SSD1B
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| SSD-1B | [SSD-1B-A1111.safetensors](https://huggingface.co/segmind/SSD-1B/resolve/main/SSD-1B-A1111.safetensors) | `-m` / `--model` | Single-file SDXL-family checkpoint |
+| Vega | [Segmind Vega](https://huggingface.co/segmind/Segmind-Vega) | `-m` / `--model` | Single-file SDXL-family checkpoint |
+| Tiny SD / SD2 | [Repositories and conversion steps](#tiny-sd-and-tiny-sd2) | `-m` / `--model` | Convert Diffusers directories first |
+| SDXS | [Ready-to-run SDXS weights](#sdxs-512-dreamshaper-weights) | `-m` / `--model` | Use the compatible autoencoder and one-step settings |
+
+### SSD1B
Note that not all of these models follow the standard parameter naming conventions. However, several useful SSD-1B models are available online, such as:
@@ -17,26 +24,25 @@ Useful LoRAs are also available:
* https://huggingface.co/seungminh/lora-swarovski-SSD-1B/resolve/main/pytorch_lora_weights.safetensors
* https://huggingface.co/kylielee505/mylcmlorassd/resolve/main/pytorch_lora_weights.safetensors
-## Vega
+### Vega
Segmind's Vega model is available online here:
* https://huggingface.co/segmind/Segmind-Vega/resolve/main/segmind-vega.safetensors
-
+
VegaRT is an example for an LCM-LoRA:
* https://huggingface.co/segmind/Segmind-VegaRT/resolve/main/pytorch_lora_weights.safetensors
Both files can be used out-of-the-box, unlike the models described in next sections.
-
-## SD1.x, SD2.x with tiny U-Nets
+### Tiny SD and Tiny SD2
These models require conversion before use. You will need a Python script provided by the diffusers team, available on GitHub:
* https://raw.githubusercontent.com/huggingface/diffusers/refs/heads/main/scripts/convert_diffusers_to_original_stable_diffusion.py
-### SD2.x
+#### SD2.x
NotaAI provides the following model online:
@@ -51,15 +57,21 @@ pipe = StableDiffusionPipeline.from_pretrained("nota-ai/bk-sdm-v2-tiny",cache_di
Second, create the .safetensors file by running:
-```bash
-python convert_diffusers_to_original_stable_diffusion.py \
- --model_path models--nota-ai--bk-sdm-v2-tiny/snapshots/68277af553777858cd47e133f92e4db47321bc74 \
- --checkpoint_path bk-sdm-v2-tiny.safetensors --half --use_safetensors
+**Windows (PowerShell)**
+
+```powershell
+python convert_diffusers_to_original_stable_diffusion.py --model_path models--nota-ai--bk-sdm-v2-tiny/snapshots/68277af553777858cd47e133f92e4db47321bc74 --checkpoint_path bk-sdm-v2-tiny.safetensors --half --use_safetensors
+```
+
+**Linux/macOS**
+
+```sh
+python convert_diffusers_to_original_stable_diffusion.py --model_path models--nota-ai--bk-sdm-v2-tiny/snapshots/68277af553777858cd47e133f92e4db47321bc74 --checkpoint_path bk-sdm-v2-tiny.safetensors --half --use_safetensors
```
This will generate the **file bk-sdm-v2-tiny.safetensors**, which is now ready for use with sd.cpp.
-### SD1.x
+#### SD1.x
Several Tiny SD 1.x models are available online, such as:
@@ -68,9 +80,9 @@ Several Tiny SD 1.x models are available online, such as:
* https://huggingface.co/nota-ai/bk-sdm-tiny
These models also require conversion, partly because some tensors are stored in a non-contiguous manner. To create a usable checkpoint file, follow these simple steps:
-Download and prepare the model using Python:
+Download and prepare the model using Python:
-##### Download the model using Python on your computer, for example this way:
+Download the model using Python on your computer, for example this way:
```python
import torch
@@ -82,37 +94,109 @@ for param in unet.parameters():
pipe.save_pretrained("segmindtiny-sd", safe_serialization=True)
```
-##### Run the conversion script:
+Run the conversion script:
+
+**Windows (PowerShell)**
-```bash
-python convert_diffusers_to_original_stable_diffusion.py \
- --model_path ./segmindtiny-sd \
- --checkpoint_path ./segmind_tiny-sd.safetensors --half --use_safetensors
+```powershell
+python convert_diffusers_to_original_stable_diffusion.py --model_path .\segmindtiny-sd --checkpoint_path .\segmind_tiny-sd.safetensors --half --use_safetensors
```
-The file segmind_tiny-sd.safetensors will be generated and is now ready for use with sd.cpp. You can follow a similar process for the other models mentioned above.
+**Linux/macOS**
+```sh
+python convert_diffusers_to_original_stable_diffusion.py --model_path ./segmindtiny-sd --checkpoint_path ./segmind_tiny-sd.safetensors --half --use_safetensors
+```
-### SDXS-512-DreamShaper
+The file segmind_tiny-sd.safetensors will be generated and is now ready for use with sd.cpp. You can follow a similar process for the other models mentioned above.
+
+### SDXS-512-DreamShaper weights
Another very tiny and **incredibly fast** model is SDXS by IDKiro et al. The authors refer to it as *"Real-Time One-Step Latent Diffusion Models with Image Conditions"*. For details read the paper: https://arxiv.org/pdf/2403.16627 . Once again the authors removed some more blocks of U-Net part and unlike other SD1 models they use an adjusted _AutoEncoderTiny_ instead of default _AutoEncoderKL_ for the VAE part.
-##### Some ready-to-run SDXS-512 model files are available online, such as:
+
+Some ready-to-run SDXS-512 model files are available online, such as:
* https://huggingface.co/akleine/sdxs-512
* https://huggingface.co/concedo/sdxs-512-tinySDdistilled-GGUF
-##### Run the model as follows:
-```bash
-~/stable-diffusion.cpp/build/bin/sd-cli -m sdxs.safetensors -p "portrait of a lovely cat" \
- --cfg-scale 1 --steps 1
-```
-Both options: ``` --cfg-scale 1 ``` and ``` --steps 1 ``` are mandatory here.
-
-### SDXS-512-0.9
+### SDXS-512-0.9 weights
Even though the name "SDXS-512-0.9" is similar to "SDXS-512-DreamShaper", it is *completely different* but also **incredibly fast**. Sometimes it is preferred, so try it yourself.
-##### Download a ready-to-run file from here:
+
+Download a ready-to-run file from here:
* https://huggingface.co/akleine/sdxs-09
-For the use of this model, both options ``` --cfg-scale 1 ``` and ``` --steps 1 ``` are again absolutely necessary.
+For the use of this model, both options `--cfg-scale 1` and `--steps 1` are again absolutely necessary.
+
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| SDXL (`sdxl-checkpoint`) | `model`, `vae`, `tae` |
+| SD 1.x (`sd1-checkpoint`) | `model`, `vae`, `tae` |
+| SD 2.1 512 (`sd2-512-checkpoint`) | `model`, `vae`, `tae` |
+| SDXS (`sdxs`) | `model`, `vae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### SSD1B
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe -m ..\models\checkpoints\SSD-1B-A1111.safetensors -p "a lovely cat"
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli -m ../models/checkpoints/SSD-1B-A1111.safetensors -p "a lovely cat"
+```
+
+#### SDXS-512-DreamShaper
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\sdxs.safetensors `
+ -p "portrait of a lovely cat" `
+ --cfg-scale 1 `
+ --steps 1
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -m ../models/checkpoints/sdxs.safetensors \
+ -p "portrait of a lovely cat" \
+ --cfg-scale 1 \
+ --steps 1
+```
+
+Both options: `--cfg-scale 1` and `--steps 1` are mandatory here.
+
+## Notes and limitations
+
+SSD-1B, Vega, and Tiny SD variants reduce the base model size. Details are in the
+[SSD-1B paper](https://arxiv.org/abs/2401.02677v1) and
+[Tiny SD paper](https://arxiv.org/pdf/2305.15798.pdf). Follow the [SDXS generation settings](#sdxs-512-dreamshaper); CFG 1 and one step are required.
+
+Run the Python conversion commands in [Model files](#model-files) from the source repository root,
+with the listed conversion script and Python dependencies installed. Return to
+the build directory for the platform-specific CLI commands.
diff --git a/docs/models/ernie_image.md b/docs/models/ernie_image.md
index a12eb9a..e4e3069 100644
--- a/docs/models/ernie_image.md
+++ b/docs/models/ernie_image.md
@@ -1,35 +1,99 @@
-# How to Use
+# ERNIE-Image
+
+ERNIE-Image and ERNIE-Image-Turbo generate images from text using the FLUX.2 VAE
+and a Ministral 3 3B text encoder.
You can run ERNIE-Image with stable-diffusion.cpp on GPUs with 4GB of VRAM — or even less.
-## Download weights
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| ERNIE-Image-Turbo | [Safetensors](https://huggingface.co/Comfy-Org/ERNIE-Image/tree/main/diffusion_models)<br>[GGUF](https://huggingface.co/unsloth/ERNIE-Image-Turbo-GGUF/tree/main) | `--diffusion-model` | Choose Turbo or Base |
+| ERNIE-Image | [Safetensors](https://huggingface.co/Comfy-Org/ERNIE-Image/tree/main/diffusion_models)<br>[GGUF](https://huggingface.co/unsloth/ERNIE-Image-GGUF/tree/main) | `--diffusion-model` | Choose Turbo or Base |
+| FLUX.2 VAE | [Safetensors](https://huggingface.co/Comfy-Org/ERNIE-Image/tree/main/vae) | `--vae` | Required for these examples |
+| Ministral 3 3B text encoder | [Safetensors](https://huggingface.co/Comfy-Org/ERNIE-Image/tree/main/text_encoders)<br>[GGUF](https://huggingface.co/unsloth/Ministral-3-3B-Instruct-2512-GGUF/tree/main) | `--llm` | Required |
+
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| ERNIE Image Turbo (`ernie-image-turbo`) | `diffusion_model`, `llm`, `vae`, `tae` |
+| ERNIE Image (`ernie-image`) | `diffusion_model`, `llm`, `vae`, `tae` |
-- Download ERNIE-Image-Turbo
- - safetensors: https://huggingface.co/Comfy-Org/ERNIE-Image/tree/main/diffusion_models
- - gguf: https://huggingface.co/unsloth/ERNIE-Image-Turbo-GGUF/tree/main
-- Download ERNIE-Image
- - safetensors: https://huggingface.co/Comfy-Org/ERNIE-Image/tree/main/diffusion_models
- - gguf: https://huggingface.co/unsloth/ERNIE-Image-GGUF/tree/main
-- Download vae
- - safetensors: https://huggingface.co/Comfy-Org/ERNIE-Image/tree/main/vae
-- Download ministral 3b
- - safetensors: https://huggingface.co/Comfy-Org/ERNIE-Image/tree/main/text_encoders
- - gguf: https://huggingface.co/unsloth/Ministral-3-3B-Instruct-2512-GGUF/tree/main
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
-## Examples
+### CLI
-### ERNIE-Image-Turbo
+#### ERNIE-Image-Turbo
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\ernie-image-turbo.safetensors `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ --llm ..\models\text_encoders\ministral-3-3b.safetensors `
+ -p "a lovely cat" `
+ --cfg-scale 1.0 `
+ --steps 8 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\ernie-image-turbo.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\ministral-3-3b.safetensors -p "a lovely cat" --cfg-scale 1.0 --steps 8 -v --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/ernie-image-turbo.safetensors \
+ --vae ../models/vae/flux2_ae.safetensors \
+ --llm ../models/text_encoders/ministral-3-3b.safetensors \
+ -p "a lovely cat" \
+ --cfg-scale 1.0 \
+ --steps 8 \
+ --offload-to-cpu \
+ -v
```
<img width="256" alt="ERNIE-Image Turbo example" src="../../assets/ernie_image/turbo_example.png" />
-### ERNIE-Image
+#### ERNIE-Image
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\ernie-image-UD-Q4_K_M.gguf `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ --llm ..\models\text_encoders\ministral-3-3b.safetensors `
+ -p "a lovely cat" `
+ --cfg-scale 5.0 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\ernie-image-UD-Q4_K_M.gguf --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\ministral-3-3b.safetensors -p "a lovely cat" --cfg-scale 5.0 -v --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/ernie-image-UD-Q4_K_M.gguf \
+ --vae ../models/vae/flux2_ae.safetensors \
+ --llm ../models/text_encoders/ministral-3-3b.safetensors \
+ -p "a lovely cat" \
+ --cfg-scale 5.0 \
+ --offload-to-cpu \
+ -v
```
<img width="256" alt="ERNIE-Image example" src="../../assets/ernie_image/example.png" />
diff --git a/docs/models/esrgan.md b/docs/models/esrgan.md
index 4068ef1..3d1a589 100644
--- a/docs/models/esrgan.md
+++ b/docs/models/esrgan.md
@@ -1,13 +1,42 @@
-## Using ESRGAN to upscale results
+# ESRGAN and MoSR
-You can use ESRGAN—such as the model [RealESRGAN_x4plus_anime_6B.pth](https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.2.4/RealESRGAN_x4plus_anime_6B.pth)—to upscale the generated images and improve their overall resolution and clarity.
+ESRGAN and compatible MoSR weights upscale generated images. Pass the chosen
+upscaler with `--upscale-model`.
-MoSR models with the PixelShuffle upsampler, such as [4xNomos2_hq_mosr.pth](https://github.com/Phhofm/models/releases/download/4xNomos2_hq_mosr/4xNomos2_hq_mosr.pth), are also supported. The architecture is detected from the weights, so they are used the same way as ESRGAN models.
+## Model files
-RGBA images, including Qwen Image 2.1 output, keep their alpha channel during model upscaling and hires fix. The upscaler processes the RGB channels; the alpha channel is resized with bilinear interpolation and recombined with the upscaled image.
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Base model | [Stable Diffusion checkpoint](sd.md) | `-m` / `--model` | Required for generation below |
+| ESRGAN upscaler | [RealESRGAN_x4plus_anime_6B.pth](https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.2.4/RealESRGAN_x4plus_anime_6B.pth) | `--upscale-model` | Choose a compatible upscaler |
+| MoSR upscaler | [4xNomos2_hq_mosr.pth](https://github.com/Phhofm/models/releases/download/4xNomos2_hq_mosr/4xNomos2_hq_mosr.pth) | `--upscale-model` | Alternative; requires the PixelShuffle upsampler |
-- Specify the model path using the `--upscale-model PATH` parameter. example:
+## Usage
-```bash
-sd-cli -m ../models/v1-5-pruned-emaonly.safetensors -p "a lovely cat" --upscale-model ../models/RealESRGAN_x4plus_anime_6B.pth
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### CLI
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\v1-5-pruned-emaonly.safetensors `
+ --upscale-model ..\models\upscale_models\RealESRGAN_x4plus_anime_6B.pth `
+ -p "a lovely cat"
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -m ../models/checkpoints/v1-5-pruned-emaonly.safetensors \
+ --upscale-model ../models/upscale_models/RealESRGAN_x4plus_anime_6B.pth \
+ -p "a lovely cat"
```
+
+## Notes and limitations
+
+RGBA output retains its alpha channel during model upscaling and hires fix.
+The upscaler processes RGB; alpha is resized with bilinear interpolation and
+recombined with the result. The model architecture is detected from the weights.
diff --git a/docs/models/fibo2.md b/docs/models/fibo2.md
index d440c95..4919bda 100644
--- a/docs/models/fibo2.md
+++ b/docs/models/fibo2.md
@@ -1,47 +1,148 @@
-# How to Use
+# Fibo 2.0
Fibo 2.0 uses a Fibo diffusion transformer, the standard FLUX.2 VAE, and Qwen3-VL 4B as the LLM text encoder. The Qwen tokenizer is built in.
-## Download weights
+## Model files
-- Download Fibo 2.0 Dev
- - safetensors: https://huggingface.co/Comfy-Org/Fibo-2.0/tree/main/diffusion_models
-- Download Fibo 2.0 Edit Turbo
- - safetensors: https://huggingface.co/Comfy-Org/Fibo-2.0/tree/main/diffusion_models
-- Download vae
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.2-dev/tree/main
-- Download Qwen3-VL 4B
- - safetensors: https://huggingface.co/Comfy-Org/Fibo-2.0/tree/main/text_encoders
- - gguf: https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct-GGUF/tree/main
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Fibo 2.0 Dev | [Safetensors](https://huggingface.co/Comfy-Org/Fibo-2.0/tree/main/diffusion_models) | `--diffusion-model` | Choose matching variant |
+| Fibo 2.0 Edit Turbo | [Safetensors](https://huggingface.co/Comfy-Org/Fibo-2.0/tree/main/diffusion_models) | `--diffusion-model` | Choose matching variant |
+| vae | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.2-dev/tree/main) | `--vae` | Use matching VAE |
+| Qwen3-VL 4B | [Safetensors](https://huggingface.co/Comfy-Org/Fibo-2.0/tree/main/text_encoders)<br>[GGUF](https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct-GGUF/tree/main) | `--llm` | Use matching text encoder |
The original Diffusers weights from [briaai/Fibo-2.0-dev](https://huggingface.co/briaai/Fibo-2.0-dev) and [briaai/Fibo-2.0-edit-turbo](https://huggingface.co/briaai/Fibo-2.0-edit-turbo) are also supported. Pass the transformer's `diffusion_pytorch_model.safetensors.index.json` to `--diffusion-model` and keep its shards alongside it.
INT8 convrot weights load directly; see [INT8 convrot](../guides/int8_convrot.md) for backend requirements.
-## Examples
+## Usage
-### Fibo 2.0 Dev
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Fibo 2.0 Dev (`fibo2-dev`) | `diffusion_model`, `llm`, `llm_vision`, `vae` |
+| Fibo 2.0 Edit Turbo (`fibo2-edit-turbo`) | `diffusion_model`, `llm`, `llm_vision`, `vae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Fibo 2.0 Dev
Dev supports both text-to-image generation and reference-image editing.
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\fibo2_dev_int8_convrot.safetensors `
+ --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf `
+ --llm_vision ..\models\text_encoders\Qwen3-VL-4B-Instruct-mmproj-BF16.gguf `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ -p "a lovely cat holding a sign says 'fibo2.cpp'" `
+ --cfg-scale 5.0 `
+ --sampling-method euler `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\fibo2_dev_int8_convrot.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --llm_vision ..\models\text_encoders\Qwen3-VL-4B-Instruct-mmproj-BF16.gguf --vae ..\models\vae\flux2_ae.safetensors -p "a lovely cat holding a sign says 'fibo2.cpp'" --cfg-scale 5.0 --sampling-method euler -v --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/fibo2_dev_int8_convrot.safetensors \
+ --llm ../models/text_encoders/Qwen3-VL-4B-Instruct-Q4_K_M.gguf \
+ --llm_vision ../models/text_encoders/Qwen3-VL-4B-Instruct-mmproj-BF16.gguf \
+ --vae ../models/vae/flux2_ae.safetensors \
+ -p "a lovely cat holding a sign says 'fibo2.cpp'" \
+ --cfg-scale 5.0 \
+ --sampling-method euler \
+ --offload-to-cpu \
+ -v
```
<img src="../../assets/fibo2/t2i.png" />
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\fibo2_dev_int8_convrot.safetensors `
+ --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf `
+ --llm_vision ..\models\text_encoders\Qwen3-VL-4B-Instruct-mmproj-BF16.gguf `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ -r ..\inputs\flux\flux1-dev-q8_0.png `
+ -p "change 'flux.cpp' to 'fibo2.cpp'" `
+ --cfg-scale 5.0 `
+ --sampling-method euler `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\fibo2_dev_int8_convrot.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --llm_vision ..\models\text_encoders\Qwen3-VL-4B-Instruct-mmproj-BF16.gguf --vae ..\models\vae\flux2_ae.safetensors -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'fibo2.cpp'" --cfg-scale 5.0 --sampling-method euler -v --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/fibo2_dev_int8_convrot.safetensors \
+ --llm ../models/text_encoders/Qwen3-VL-4B-Instruct-Q4_K_M.gguf \
+ --llm_vision ../models/text_encoders/Qwen3-VL-4B-Instruct-mmproj-BF16.gguf \
+ --vae ../models/vae/flux2_ae.safetensors \
+ -r ../inputs/flux/flux1-dev-q8_0.png \
+ -p "change 'flux.cpp' to 'fibo2.cpp'" \
+ --cfg-scale 5.0 \
+ --sampling-method euler \
+ --offload-to-cpu \
+ -v
```
<img src="../../assets/fibo2/dev_edit.png" />
-### Fibo 2.0 Edit Turbo
+#### Fibo 2.0 Edit Turbo
Edit Turbo is distilled for reference-image editing in 4 steps with CFG 1.
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\fibo2_edit_turbo_int8_convrot.safetensors `
+ --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf `
+ --llm_vision ..\models\text_encoders\Qwen3-VL-4B-Instruct-mmproj-BF16.gguf `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ -r ..\inputs\flux\flux1-dev-q8_0.png `
+ -p "change 'flux.cpp' to 'fibo2.cpp'" `
+ --cfg-scale 1 `
+ --steps 4 `
+ --sampling-method euler `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\fibo2_edit_turbo_int8_convrot.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --llm_vision ..\models\text_encoders\Qwen3-VL-4B-Instruct-mmproj-BF16.gguf --vae ..\models\vae\flux2_ae.safetensors -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'fibo2.cpp'" --cfg-scale 1 --steps 4 --sampling-method euler -v --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/fibo2_edit_turbo_int8_convrot.safetensors \
+ --llm ../models/text_encoders/Qwen3-VL-4B-Instruct-Q4_K_M.gguf \
+ --llm_vision ../models/text_encoders/Qwen3-VL-4B-Instruct-mmproj-BF16.gguf \
+ --vae ../models/vae/flux2_ae.safetensors \
+ -r ../inputs/flux/flux1-dev-q8_0.png \
+ -p "change 'flux.cpp' to 'fibo2.cpp'" \
+ --cfg-scale 1 \
+ --steps 4 \
+ --sampling-method euler \
+ --offload-to-cpu \
+ -v
```
The BF16 files accept the same options. Use dimensions divisible by 16. Repeat `-r` to use multiple reference images; instructions can refer to `<image_1>`, `<image_2>`, etc. See [Image Editing](../guides/edit.md) for reference-image preprocessing options. Separate GGUF text encoders need their vision projector passed with `--llm_vision` for editing.
diff --git a/docs/models/flux.md b/docs/models/flux.md
index 96267f5..dd67bbd 100644
--- a/docs/models/flux.md
+++ b/docs/models/flux.md
@@ -1,34 +1,106 @@
-# How to Use
+# FLUX.1
+
+FLUX.1 dev and schnell generate images from text using CLIP-L, T5-XXL, and the FLUX.1 VAE.
You can run Flux using stable-diffusion.cpp with a GPU that has 6GB or even 4GB of VRAM, without needing to offload to RAM.
-## Download weights
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| flux | If you don't want to do the conversion yourself, download the preconverted gguf model from [FLUX.1-dev-gguf](https://huggingface.co/leejet/FLUX.1-dev-gguf) or [FLUX.1-schnell](https://huggingface.co/leejet/FLUX.1-schnell-gguf)<br>Otherwise, download flux-dev from [Download](https://huggingface.co/black-forest-labs/FLUX.1-dev/blob/main/flux1-dev.safetensors) or flux-schnell from [Safetensors](https://huggingface.co/black-forest-labs/FLUX.1-schnell/blob/main/flux1-schnell.safetensors) | `--diffusion-model` | Required |
+| vae | vae from [Download](https://huggingface.co/black-forest-labs/FLUX.1-dev/blob/main/ae.safetensors) | `--vae` | Use matching VAE |
+| clip_l | clip_l from [Download](https://huggingface.co/comfyanonymous/flux_text_encoders/blob/main/clip_l.safetensors) | `--clip_l` | Required |
+| t5xxl | t5xxl from [Download](https://huggingface.co/comfyanonymous/flux_text_encoders/blob/main/t5xxl_fp16.safetensors) | `--t5xxl` | Required |
+
+### Optional conversion
-- Download flux
- - If you don't want to do the conversion yourself, download the preconverted gguf model from [FLUX.1-dev-gguf](https://huggingface.co/leejet/FLUX.1-dev-gguf) or [FLUX.1-schnell](https://huggingface.co/leejet/FLUX.1-schnell-gguf)
- - Otherwise, download flux-dev from https://huggingface.co/black-forest-labs/FLUX.1-dev/blob/main/flux1-dev.safetensors or flux-schnell from https://huggingface.co/black-forest-labs/FLUX.1-schnell/blob/main/flux1-schnell.safetensors
-- Download vae from https://huggingface.co/black-forest-labs/FLUX.1-dev/blob/main/ae.safetensors
-- Download clip_l from https://huggingface.co/comfyanonymous/flux_text_encoders/blob/main/clip_l.safetensors
-- Download t5xxl from https://huggingface.co/comfyanonymous/flux_text_encoders/blob/main/t5xxl_fp16.safetensors
+Run executable conversion examples from the build directory using the
+[shared path and shell conventions](README.md#example-conventions).
-## Convert flux weights
+#### Convert flux weights
You can download the preconverted gguf weights from [FLUX.1-dev-gguf](https://huggingface.co/leejet/FLUX.1-dev-gguf) or [FLUX.1-schnell](https://huggingface.co/leejet/FLUX.1-schnell-gguf), this way you don't have to do the conversion yourself.
For example:
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M convert `
+ -m ..\models\unet\flux1-dev.sft `
+ --type q8_0 `
+ -o ..\models\diffusion_models\flux1-dev-q8_0.gguf `
+ -v
```
-.\bin\Release\sd-cli.exe -M convert -m ..\models\unet\flux1-dev.sft -o ..\models\flux1-dev-q8_0.gguf -v --type q8_0
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M convert \
+ -m ../models/unet/flux1-dev.sft \
+ --type q8_0 \
+ -o ../models/diffusion_models/flux1-dev-q8_0.gguf \
+ -v
```
-## Run
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| FLUX.1 dev (`flux1-dev`) | `diffusion_model`, `clip_l`, `t5xxl`, `vae`, `tae` |
+| FLUX.1 schnell (`flux1-schnell`) | `diffusion_model`, `clip_l`, `t5xxl`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
-- `--cfg-scale` is recommended to be set to 1.
+### CLI
+
+- `--cfg-scale` is recommended to be set to 1.
+
+#### Flux-dev
-### Flux-dev
For example:
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\flux1-dev-q8_0.gguf `
+ --vae ..\models\vae\ae.sft `
+ --clip_l ..\models\text_encoders\clip_l.safetensors `
+ --t5xxl ..\models\text_encoders\t5xxl_fp16.safetensors `
+ -p "a lovely cat holding a sign says 'flux.cpp'" `
+ --cfg-scale 1.0 `
+ --sampling-method euler `
+ --clip-on-cpu `
+ -v
```
- .\bin\Release\sd-cli.exe --diffusion-model ..\models\flux1-dev-q8_0.gguf --vae ..\models\ae.sft --clip_l ..\models\clip_l.safetensors --t5xxl ..\models\t5xxl_fp16.safetensors -p "a lovely cat holding a sign says 'flux.cpp'" --cfg-scale 1.0 --sampling-method euler -v --clip-on-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/flux1-dev-q8_0.gguf \
+ --vae ../models/vae/ae.sft \
+ --clip_l ../models/text_encoders/clip_l.safetensors \
+ --t5xxl ../models/text_encoders/t5xxl_fp16.safetensors \
+ -p "a lovely cat holding a sign says 'flux.cpp'" \
+ --cfg-scale 1.0 \
+ --sampling-method euler \
+ --clip-on-cpu \
+ -v
```
Using formats of different precisions will yield results of varying quality.
@@ -38,29 +110,82 @@ Using formats of different precisions will yield results of varying quality.
| **Memory** | 12068.09 MB | 6394.53 MB | 6395.17 MB | 4888.16 MB | 3735.73 MB |
| **Result** |  | | | ||
-
-
-### Flux-schnell
-
-
+#### Flux-schnell
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\flux1-schnell-q8_0.gguf `
+ --vae ..\models\vae\ae.sft `
+ --clip_l ..\models\text_encoders\clip_l.safetensors `
+ --t5xxl ..\models\text_encoders\t5xxl_fp16.safetensors `
+ -p "a lovely cat holding a sign says 'flux.cpp'" `
+ --cfg-scale 1.0 `
+ --sampling-method euler `
+ --steps 4 `
+ --clip-on-cpu `
+ -v
```
- .\bin\Release\sd-cli.exe --diffusion-model ..\models\flux1-schnell-q8_0.gguf --vae ..\models\ae.sft --clip_l ..\models\clip_l.safetensors --t5xxl ..\models\t5xxl_fp16.safetensors -p "a lovely cat holding a sign says 'flux.cpp'" --cfg-scale 1.0 --sampling-method euler -v --steps 4 --clip-on-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/flux1-schnell-q8_0.gguf \
+ --vae ../models/vae/ae.sft \
+ --clip_l ../models/text_encoders/clip_l.safetensors \
+ --t5xxl ../models/text_encoders/t5xxl_fp16.safetensors \
+ -p "a lovely cat holding a sign says 'flux.cpp'" \
+ --cfg-scale 1.0 \
+ --sampling-method euler \
+ --steps 4 \
+ --clip-on-cpu \
+ -v
```
| q8_0 |
| ---- |
| |
-## Run with LoRA
+#### Run with LoRA
Since many flux LoRA training libraries have used various LoRA naming formats, it is possible that not all flux LoRA naming formats are supported. It is recommended to use LoRA with naming formats compatible with ComfyUI.
-### Flux-dev q8_0 with LoRA
+##### Flux-dev q8_0 with LoRA
- LoRA model from https://huggingface.co/XLabs-AI/flux-lora-collection/tree/main (using comfy converted version!!!)
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\flux1-dev-q8_0.gguf `
+ --vae ..\models\vae\ae.sft `
+ --clip_l ..\models\text_encoders\clip_l.safetensors `
+ --t5xxl ..\models\text_encoders\t5xxl_fp16.safetensors `
+ --lora-model-dir ..\models\loras `
+ -p "a lovely cat holding a sign says 'flux.cpp'<lora:realism_lora_comfy_converted:1>" `
+ --cfg-scale 1.0 `
+ --sampling-method euler `
+ --clip-on-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\flux1-dev-q8_0.gguf --vae ...\models\ae.sft --clip_l ..\models\clip_l.safetensors --t5xxl ..\models\t5xxl_fp16.safetensors -p "a lovely cat holding a sign says 'flux.cpp'<lora:realism_lora_comfy_converted:1>" --cfg-scale 1.0 --sampling-method euler -v --lora-model-dir ../models --clip-on-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/flux1-dev-q8_0.gguf \
+ --vae ../models/vae/ae.sft \
+ --clip_l ../models/text_encoders/clip_l.safetensors \
+ --t5xxl ../models/text_encoders/t5xxl_fp16.safetensors \
+ --lora-model-dir ../models/loras \
+ -p "a lovely cat holding a sign says 'flux.cpp'<lora:realism_lora_comfy_converted:1>" \
+ --cfg-scale 1.0 \
+ --sampling-method euler \
+ --clip-on-cpu \
+ -v
```
diff --git a/docs/models/flux2.md b/docs/models/flux2.md
index 6838c19..fdca1b2 100644
--- a/docs/models/flux2.md
+++ b/docs/models/flux2.md
@@ -1,96 +1,285 @@
-# How to Use
+# FLUX.2
-## Flux.2-dev
+FLUX.2 supports text-to-image generation and reference-image editing. Choose
+the text encoder matching the transformer variant.
-### Download weights
+## Model files
-- Download FLUX.2-dev
- - gguf: https://huggingface.co/city96/FLUX.2-dev-gguf/tree/main
-- Download vae
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.2-dev/tree/main
-- Download FLUX.2-small-decoder (full_encoder_small_decoder.safetensors) as an alternative VAE option
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.2-small-decoder/tree/main
-- Download Mistral-Small-3.2-24B-Instruct-2506-GGUF
- - gguf: https://huggingface.co/unsloth/Mistral-Small-3.2-24B-Instruct-2506-GGUF/tree/main
+### Flux.2-dev
-### Examples
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| FLUX.2 dev | [GGUF](https://huggingface.co/city96/FLUX.2-dev-gguf/tree/main) | `--diffusion-model` | Required for dev |
+| FLUX.2 VAE | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.2-dev/tree/main) | `--vae` | Choose one compatible VAE |
+| FLUX.2 small decoder | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.2-small-decoder/tree/main) | `--vae` | Alternative VAE |
+| Mistral Small 3.2 24B | [GGUF](https://huggingface.co/unsloth/Mistral-Small-3.2-24B-Instruct-2506-GGUF/tree/main) | `--llm` | Required for dev |
+### Flux.2 klein 4B / Flux.2 klein base 4B
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| FLUX.2 Klein 4B | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B)<br>[GGUF](https://huggingface.co/leejet/FLUX.2-klein-4B-GGUF/tree/main) | `--diffusion-model` | Choose Klein or Klein Base |
+| FLUX.2 Klein Base 4B | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.2-klein-base-4B)<br>[GGUF](https://huggingface.co/leejet/FLUX.2-klein-base-4B-GGUF/tree/main) | `--diffusion-model` | Choose Klein or Klein Base |
+| FLUX.2 VAE | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.2-dev/tree/main) | `--vae` | Choose one compatible VAE |
+| FLUX.2 small decoder | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.2-small-decoder/tree/main) | `--vae` | Alternative VAE |
+| Qwen3 4B | [Safetensors](https://huggingface.co/Comfy-Org/flux2-klein-4B/tree/main/split_files/text_encoders)<br>[GGUF](https://huggingface.co/unsloth/Qwen3-4B-GGUF/tree/main) | `--llm` | Required for 4B variants |
+
+### Flux.2 klein 9B / Flux.2 klein base 9B
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| FLUX.2 Klein 9B | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.2-klein-9B)<br>[GGUF](https://huggingface.co/leejet/FLUX.2-klein-9B-GGUF/tree/main) | `--diffusion-model` | Choose Klein or Klein Base |
+| FLUX.2 Klein Base 9B | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.2-klein-base-9B)<br>[GGUF](https://huggingface.co/leejet/FLUX.2-klein-base-9B-GGUF/tree/main) | `--diffusion-model` | Choose Klein or Klein Base |
+| FLUX.2 VAE | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.2-dev/tree/main) | `--vae` | Required for these examples |
+| Qwen3 8B | [Safetensors](https://huggingface.co/Comfy-Org/flux2-klein-9B/tree/main/split_files/text_encoders)<br>[GGUF](https://huggingface.co/unsloth/Qwen3-8B-GGUF/tree/main) | `--llm` | Required for 9B variants |
+
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| FLUX.2 dev (`flux2-dev`) | `diffusion_model`, `llm`, `vae`, `tae` |
+| FLUX.2 Klein 4B (`flux2-klein-4b`) | `diffusion_model`, `llm`, `vae`, `tae` |
+| FLUX.2 Klein Base 4B (`flux2-klein-base-4b`) | `diffusion_model`, `llm`, `vae`, `tae` |
+| FLUX.2 Klein 9B (`flux2-klein-9b`) | `diffusion_model`, `llm`, `vae`, `tae` |
+| FLUX.2 Klein Base 9B (`flux2-klein-base-9b`) | `diffusion_model`, `llm`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Flux.2-dev
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\flux2-dev-Q4_K_S.gguf `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ --llm ..\models\text_encoders\Mistral-Small-3.2-24B-Instruct-2506-Q4_K_M.gguf `
+ -r .\kontext_input.png `
+ -p "change 'flux.cpp' to 'flux2-dev.cpp'" `
+ --cfg-scale 1.0 `
+ --sampling-method euler `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux2-dev-Q4_K_S.gguf --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\Mistral-Small-3.2-24B-Instruct-2506-Q4_K_M.gguf -r .\kontext_input.png -p "change 'flux.cpp' to 'flux2-dev.cpp'" --cfg-scale 1.0 --sampling-method euler -v --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/flux2-dev-Q4_K_S.gguf \
+ --vae ../models/vae/flux2_ae.safetensors \
+ --llm ../models/text_encoders/Mistral-Small-3.2-24B-Instruct-2506-Q4_K_M.gguf \
+ -r ./kontext_input.png \
+ -p "change 'flux.cpp' to 'flux2-dev.cpp'" \
+ --cfg-scale 1.0 \
+ --sampling-method euler \
+ --offload-to-cpu \
+ -v
```
<img alt="flux2 example" src="../../assets/flux2/example.png" />
-## Flux.2 klein 4B / Flux.2 klein base 4B
+#### Flux.2 klein 4B / Flux.2 klein base 4B
-### Download weights
+**Windows (PowerShell)**
-- Download FLUX.2-klein-4B
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.2-klein-4B
- - gguf: https://huggingface.co/leejet/FLUX.2-klein-4B-GGUF/tree/main
-- Download FLUX.2-klein-base-4B
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.2-klein-base-4B
- - gguf: https://huggingface.co/leejet/FLUX.2-klein-base-4B-GGUF/tree/main
-- Download vae
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.2-dev/tree/main
-- Download FLUX.2-small-decoder (full_encoder_small_decoder.safetensors) as an alternative VAE option
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.2-small-decoder/tree/main
-- Download Qwen3 4b
- - safetensors: https://huggingface.co/Comfy-Org/flux2-klein-4B/tree/main/split_files/text_encoders
- - gguf: https://huggingface.co/unsloth/Qwen3-4B-GGUF/tree/main
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\flux-2-klein-4b.safetensors `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ --llm ..\models\text_encoders\qwen_3_4b.safetensors `
+ -p "a lovely cat" `
+ --cfg-scale 1.0 `
+ --steps 4 `
+ --offload-to-cpu `
+ -v
+```
-### Examples
+**Linux/macOS**
-```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-2-klein-4b.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\qwen_3_4b.safetensors -p "a lovely cat" --cfg-scale 1.0 --steps 4 -v --offload-to-cpu
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/flux-2-klein-4b.safetensors \
+ --vae ../models/vae/flux2_ae.safetensors \
+ --llm ../models/text_encoders/qwen_3_4b.safetensors \
+ -p "a lovely cat" \
+ --cfg-scale 1.0 \
+ --steps 4 \
+ --offload-to-cpu \
+ -v
```
<img alt="flux2-klein-4b" src="../../assets/flux2/flux2-klein-4b.png" />
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\flux-2-klein-4b.safetensors `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ --llm ..\models\text_encoders\qwen_3_4b.safetensors `
+ -r .\kontext_input.png `
+ -p "change 'flux.cpp' to 'klein.cpp'" `
+ --cfg-scale 1.0 `
+ --sampling-method euler `
+ --steps 4 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-2-klein-4b.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\qwen_3_4b.safetensors -r .\kontext_input.png -p "change 'flux.cpp' to 'klein.cpp'" --cfg-scale 1.0 --sampling-method euler -v --offload-to-cpu --steps 4
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/flux-2-klein-4b.safetensors \
+ --vae ../models/vae/flux2_ae.safetensors \
+ --llm ../models/text_encoders/qwen_3_4b.safetensors \
+ -r ./kontext_input.png \
+ -p "change 'flux.cpp' to 'klein.cpp'" \
+ --cfg-scale 1.0 \
+ --sampling-method euler \
+ --steps 4 \
+ --offload-to-cpu \
+ -v
```
<img alt="flux2-klein-4b-edit" src="../../assets/flux2/flux2-klein-4b-edit.png" />
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\flux-2-klein-base-4b.safetensors `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ --llm ..\models\text_encoders\qwen_3_4b.safetensors `
+ -p "a lovely cat" `
+ --cfg-scale 4.0 `
+ --steps 20 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-2-klein-base-4b.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\qwen_3_4b.safetensors -p "a lovely cat" --cfg-scale 4.0 --steps 20 -v --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/flux-2-klein-base-4b.safetensors \
+ --vae ../models/vae/flux2_ae.safetensors \
+ --llm ../models/text_encoders/qwen_3_4b.safetensors \
+ -p "a lovely cat" \
+ --cfg-scale 4.0 \
+ --steps 20 \
+ --offload-to-cpu \
+ -v
```
<img alt="flux2-klein-base-4b" src="../../assets/flux2/flux2-klein-base-4b.png" />
-## Flux.2 klein 9B / Flux.2 klein base 9B
+#### Flux.2 klein 9B / Flux.2 klein base 9B
-### Download weights
+**Windows (PowerShell)**
-- Download FLUX.2-klein-9B
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.2-klein-9B
- - gguf: https://huggingface.co/leejet/FLUX.2-klein-9B-GGUF/tree/main
-- Download FLUX.2-klein-base-9B
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.2-klein-base-9B
- - gguf: https://huggingface.co/leejet/FLUX.2-klein-base-9B-GGUF/tree/main
-- Download vae
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.2-dev/tree/main
-- Download Qwen3 8B
- - safetensors: https://huggingface.co/Comfy-Org/flux2-klein-9B/tree/main/split_files/text_encoders
- - gguf: https://huggingface.co/unsloth/Qwen3-8B-GGUF/tree/main
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\flux-2-klein-9b.safetensors `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ --llm ..\models\text_encoders\qwen_3_8b.safetensors `
+ -p "a lovely cat" `
+ --cfg-scale 1.0 `
+ --steps 4 `
+ --offload-to-cpu `
+ -v
+```
-### Examples
+**Linux/macOS**
-```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-2-klein-9b.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\qwen_3_8b.safetensors -p "a lovely cat" --cfg-scale 1.0 --steps 4 -v --offload-to-cpu
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/flux-2-klein-9b.safetensors \
+ --vae ../models/vae/flux2_ae.safetensors \
+ --llm ../models/text_encoders/qwen_3_8b.safetensors \
+ -p "a lovely cat" \
+ --cfg-scale 1.0 \
+ --steps 4 \
+ --offload-to-cpu \
+ -v
```
<img alt="flux2-klein-9b" src="../../assets/flux2/flux2-klein-9b.png" />
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\flux-2-klein-9b.safetensors `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ --llm ..\models\text_encoders\qwen_3_8b.safetensors `
+ -r .\kontext_input.png `
+ -p "change 'flux.cpp' to 'klein.cpp'" `
+ --cfg-scale 1.0 `
+ --sampling-method euler `
+ --steps 4 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-2-klein-9b.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\qwen_3_8b.safetensors -r .\kontext_input.png -p "change 'flux.cpp' to 'klein.cpp'" --cfg-scale 1.0 --sampling-method euler -v --offload-to-cpu --steps 4
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/flux-2-klein-9b.safetensors \
+ --vae ../models/vae/flux2_ae.safetensors \
+ --llm ../models/text_encoders/qwen_3_8b.safetensors \
+ -r ./kontext_input.png \
+ -p "change 'flux.cpp' to 'klein.cpp'" \
+ --cfg-scale 1.0 \
+ --sampling-method euler \
+ --steps 4 \
+ --offload-to-cpu \
+ -v
```
<img alt="flux2-klein-9b-edit" src="../../assets/flux2/flux2-klein-9b-edit.png" />
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\flux-2-klein-base-9b.safetensors `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ --llm ..\models\text_encoders\qwen_3_8b.safetensors `
+ -p "a lovely cat" `
+ --cfg-scale 4.0 `
+ --steps 20 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-2-klein-base-9b.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\qwen_3_8b.safetensors -p "a lovely cat" --cfg-scale 4.0 --steps 20 -v --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/flux-2-klein-base-9b.safetensors \
+ --vae ../models/vae/flux2_ae.safetensors \
+ --llm ../models/text_encoders/qwen_3_8b.safetensors \
+ -p "a lovely cat" \
+ --cfg-scale 4.0 \
+ --steps 20 \
+ --offload-to-cpu \
+ -v
```
-<img alt="flux2-klein-base-9b" src="../../assets/flux2/flux2-klein-base-9b.png" />
\ No newline at end of file
+<img alt="flux2-klein-base-9b" src="../../assets/flux2/flux2-klein-base-9b.png" />
diff --git a/docs/models/flux3.md b/docs/models/flux3.md
index f4986bb..7591d7c 100644
--- a/docs/models/flux3.md
+++ b/docs/models/flux3.md
@@ -1,48 +1,142 @@
-# How to Use
+# FLUX.3 Image
FLUX.3 Image Klein uses a FLUX.3 diffusion transformer, the FLUX.2 VAE, and Qwen3-VL 4B as the LLM text encoder.
-## Download weights
-
-- Download FLUX.3 Image Klein
- - safetensors: https://huggingface.co/black-forest-labs/flux-3-image-klein/tree/main
- - gguf: https://huggingface.co/leejet/flux-3-image-klein-GGUF/tree/main
-- Download FLUX.3 Image Klein Base
- - safetensors: https://huggingface.co/black-forest-labs/flux-3-image-klein-base/tree/main
- - gguf: https://huggingface.co/leejet/flux-3-image-klein-base-GGUF/tree/main
-- Download vae
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.2-dev/tree/main
- - The `ae.safetensors` included with FLUX.3 can also be used.
-- Download Qwen3-VL 4B
- - safetensors: https://huggingface.co/Comfy-Org/Krea-2/tree/main/text_encoders
- - gguf: https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct-GGUF/tree/main
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| FLUX.3 Image Klein | [Safetensors](https://huggingface.co/black-forest-labs/flux-3-image-klein/tree/main)<br>[GGUF](https://huggingface.co/leejet/flux-3-image-klein-GGUF/tree/main) | `--diffusion-model` | Choose matching variant |
+| FLUX.3 Image Klein Base | [Safetensors](https://huggingface.co/black-forest-labs/flux-3-image-klein-base/tree/main)<br>[GGUF](https://huggingface.co/leejet/flux-3-image-klein-base-GGUF/tree/main) | `--diffusion-model` | Choose matching variant |
+| vae | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.2-dev/tree/main)<br>The `ae.safetensors` included with FLUX.3 can also be used. | `--vae` | Use matching VAE |
+| Qwen3-VL 4B | [Safetensors](https://huggingface.co/Comfy-Org/Krea-2/tree/main/text_encoders)<br>[GGUF](https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct-GGUF/tree/main) | `--llm` | Use matching text encoder |
Use the root `model.safetensors` for the diffusion model.
-## Examples
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| FLUX.3 Image Klein (`flux3-klein`) | `diffusion_model`, `llm`, `vae`, `tae` |
+| FLUX.3 Image Klein Base (`flux3-klein-base`) | `diffusion_model`, `llm`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
-### FLUX.3 Image Klein
+### CLI
+
+#### FLUX.3 Image Klein
The distilled model uses 16 steps and CFG 1.0.
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\flux-3-image-klein.safetensors `
+ --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ -p "a lovely cat holding a sign says 'flux3.cpp'" `
+ --cfg-scale 1.0 `
+ --steps 16 `
+ --sampling-method euler `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-3-image-klein.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --vae ..\models\vae\flux2_ae.safetensors -p "a lovely cat holding a sign says 'flux3.cpp'" --cfg-scale 1.0 --steps 16 --sampling-method euler -v --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/flux-3-image-klein.safetensors \
+ --llm ../models/text_encoders/Qwen3-VL-4B-Instruct-Q4_K_M.gguf \
+ --vae ../models/vae/flux2_ae.safetensors \
+ -p "a lovely cat holding a sign says 'flux3.cpp'" \
+ --cfg-scale 1.0 \
+ --steps 16 \
+ --sampling-method euler \
+ --offload-to-cpu \
+ -v
```
<img src="../../assets/flux3/flux3-image-klein.png" />
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\flux-3-image-klein.safetensors `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf `
+ -r ..\inputs\flux\flux1-dev-q8_0.png `
+ -p "change 'flux.cpp' to 'flux3-image-klein.cpp'" `
+ --cfg-scale 1.0 `
+ --sampling-method euler `
+ --steps 16 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-3-image-klein.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'flux3-image-klein.cpp'" --cfg-scale 1.0 --sampling-method euler -v --offload-to-cpu --steps 16
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/flux-3-image-klein.safetensors \
+ --vae ../models/vae/flux2_ae.safetensors \
+ --llm ../models/text_encoders/Qwen3-VL-4B-Instruct-Q4_K_M.gguf \
+ -r ../inputs/flux/flux1-dev-q8_0.png \
+ -p "change 'flux.cpp' to 'flux3-image-klein.cpp'" \
+ --cfg-scale 1.0 \
+ --sampling-method euler \
+ --steps 16 \
+ --offload-to-cpu \
+ -v
```
<img src="../../assets/flux3/flux3-image-klein-edit.png" />
Repeat `-r` to use multiple reference images, up to 10. See [Image Editing](../guides/edit.md) for reference-image preprocessing options.
-### FLUX.3 Image Klein Base
-
+#### FLUX.3 Image Klein Base
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\flux-3-image-klein-base.safetensors `
+ --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ -p "a lovely cat holding a sign says 'flux3.cpp'" `
+ --cfg-scale 3.5 `
+ --steps 20 `
+ --sampling-method euler `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-3-image-klein-base.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --vae ..\models\vae\flux2_ae.safetensors -p "a lovely cat holding a sign says 'flux3.cpp'" --cfg-scale 3.5 --steps 20 --sampling-method euler -v --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/flux-3-image-klein-base.safetensors \
+ --llm ../models/text_encoders/Qwen3-VL-4B-Instruct-Q4_K_M.gguf \
+ --vae ../models/vae/flux2_ae.safetensors \
+ -p "a lovely cat holding a sign says 'flux3.cpp'" \
+ --cfg-scale 3.5 \
+ --steps 20 \
+ --sampling-method euler \
+ --offload-to-cpu \
+ -v
```
<img src="../../assets/flux3/flux3-image-klein-base.png" />
diff --git a/docs/models/hidream_o1_image.md b/docs/models/hidream_o1_image.md
index 2fc29e3..09f7ac7 100644
--- a/docs/models/hidream_o1_image.md
+++ b/docs/models/hidream_o1_image.md
@@ -1,20 +1,59 @@
-# How to Use
+# HiDream-O1-Image
-## Download weights
+HiDream-O1-Image uses a bundled model checkpoint. The example below uses the Dev checkpoint.
-- Download HiDream-O1-Image-Dev
- - safetensors: https://huggingface.co/Comfy-Org/HiDream-O1-Image/tree/main/checkpoints
-- Download HiDream-O1-Image
- - safetensors: https://huggingface.co/Comfy-Org/HiDream-O1-Image/tree/main/checkpoints
+## Model files
-## Examples
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| HiDream-O1-Image-Dev | [Safetensors](https://huggingface.co/Comfy-Org/HiDream-O1-Image/tree/main/checkpoints) | `--model` | Choose matching variant |
+| HiDream-O1-Image | [Safetensors](https://huggingface.co/Comfy-Org/HiDream-O1-Image/tree/main/checkpoints) | `--model` | Choose matching variant |
-### HiDream-O1-Image-Dev
+## Usage
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| HiDream O1 Image dev (`hidream-o1-dev`) | `model` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### HiDream-O1-Image-Dev
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\hidream_o1_image_dev_bf16.safetensors `
+ -p "a lovely cat holding a sign says 'hidream o1 cpp'" `
+ --cfg-scale 1.0 `
+ -H 1024 `
+ -W 1024 `
+ -v
```
-.\bin\Release\sd-cli.exe -m ..\models\diffusion_models\hidream_o1_image_dev_bf16.safetensors -p "a lovely cat holding a sign says
-'hidream o1 cpp'" --cfg-scale 1.0 -v -H 1024 -W 1024
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -m ../models/checkpoints/hidream_o1_image_dev_bf16.safetensors \
+ -p "a lovely cat holding a sign says 'hidream o1 cpp'" \
+ --cfg-scale 1.0 \
+ -H 1024 \
+ -W 1024 \
+ -v
```
<img width="256" alt="HiDream-O1-Image-Dev example" src="../../assets/hidream-o1/dev_example.png" />
-
diff --git a/docs/models/hunyuan_video.md b/docs/models/hunyuan_video.md
index cee2a2a..f31f8cf 100644
--- a/docs/models/hunyuan_video.md
+++ b/docs/models/hunyuan_video.md
@@ -1,24 +1,82 @@
# HunyuanVideo 1.5
-HunyuanVideo 1.5 uses a HunyuanVideo diffusion transformer, a causal video VAE, Qwen2.5-VL 7B for the main text conditioning,
+HunyuanVideo 1.5 uses a HunyuanVideo diffusion transformer, a causal video VAE, Qwen2.5-VL 7B for the main text conditioning,
and ByT5 Small GlyphXL for glyph-aware text conditioning.
-## Download weights
+## Model files
-- Download HunyuanVideo 1.5
- - safetensors: https://huggingface.co/Comfy-Org/HunyuanVideo_1.5_repackaged/tree/main/split_files/diffusion_models
-- Download vae
- - safetensors: https://huggingface.co/Comfy-Org/HunyuanVideo_1.5_repackaged/tree/main/split_files/vae
-- Download qwen_2.5_vl 7b
- - safetensors: https://huggingface.co/Comfy-Org/Qwen-Image_ComfyUI/tree/main/split_files/text_encoders
- - gguf: https://huggingface.co/mradermacher/Qwen2.5-VL-7B-Instruct-GGUF/tree/main
-- Download byt5 small glyphxl
- - safetensros: https://huggingface.co/Comfy-Org/HunyuanVideo_1.5_repackaged/tree/main/split_files/text_encoders
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| HunyuanVideo 1.5 | [Safetensors](https://huggingface.co/Comfy-Org/HunyuanVideo_1.5_repackaged/tree/main/split_files/diffusion_models) | `--diffusion-model` | Required |
+| vae | [Safetensors](https://huggingface.co/Comfy-Org/HunyuanVideo_1.5_repackaged/tree/main/split_files/vae) | `--vae` | Use matching VAE |
+| qwen_2.5_vl 7b | [Safetensors](https://huggingface.co/Comfy-Org/Qwen-Image_ComfyUI/tree/main/split_files/text_encoders)<br>[GGUF](https://huggingface.co/mradermacher/Qwen2.5-VL-7B-Instruct-GGUF/tree/main) | `--llm` | Use matching text encoder |
+| byt5 small glyphxl | safetensros: [Download](https://huggingface.co/Comfy-Org/HunyuanVideo_1.5_repackaged/tree/main/split_files/text_encoders) | `--t5xxl` | Required |
-## Text-to-video example
+## Usage
-```shell
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\hunyuanvideo1.5_720p_t2v_fp16.safetensors --vae ..\models\vae\hunyuanvideo15_vae_fp16.safetensors --llm ..\models\text_encoders\qwen_2.5_vl_7b.safetensors --t5xxl ..\models\text_encoders\byt5_small_glyphxl_fp16.safetensors -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -W 1280 -H 720 --offload-to-cpu --video-frames 33 --vae-tiling
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| HunyuanVideo 1.5 T2V (`hunyuan-video-15-t2v`) | `diffusion_model`, `llm`, `t5xxl`, `vae`, `tae` |
+| HunyuanVideo 1.5 I2V (`hunyuan-video-15-i2v`) | `diffusion_model`, `llm`, `t5xxl`, `vae`, `tae` |
+
+Use the T2V checkpoint with the T2V recipe. For I2V, select the I2V checkpoint
+and recipe, then supply the starting image in Video Generation.
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Text-to-video example
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\hunyuanvideo1.5_720p_t2v_fp16.safetensors `
+ --vae ..\models\vae\hunyuanvideo15_vae_fp16.safetensors `
+ --llm ..\models\text_encoders\qwen_2.5_vl_7b.safetensors `
+ --t5xxl ..\models\text_encoders\byt5_small_glyphxl_fp16.safetensors `
+ -p "a lovely cat" `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ -W 1280 `
+ -H 720 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ --vae-tiling `
+ -v
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/hunyuanvideo1.5_720p_t2v_fp16.safetensors \
+ --vae ../models/vae/hunyuanvideo15_vae_fp16.safetensors \
+ --llm ../models/text_encoders/qwen_2.5_vl_7b.safetensors \
+ --t5xxl ../models/text_encoders/byt5_small_glyphxl_fp16.safetensors \
+ -p "a lovely cat" \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ -W 1280 \
+ -H 720 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ --vae-tiling \
+ -v
```
-<video src=../../assets/hunyuan_video/hy1.5_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
\ No newline at end of file
+<video src=../../assets/hunyuan_video/hy1.5_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
diff --git a/docs/models/ideogram4.md b/docs/models/ideogram4.md
index 61c09f4..64e8121 100644
--- a/docs/models/ideogram4.md
+++ b/docs/models/ideogram4.md
@@ -1,17 +1,17 @@
-# How to Use
+# Ideogram4
-## Download weights
+Ideogram4 generates images from text. Classifier-free guidance uses a separate matching unconditional transformer.
-- Download Ideogram4
- - safetensors: https://huggingface.co/ideogram-ai/ideogram-4-fp8/tree/main/transformer
-- Download Ideogram4 uncond
- - safetensors: https://huggingface.co/ideogram-ai/ideogram-4-fp8/tree/main/unconditional_transformer
-- Download vae
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.2-dev/tree/main
-- Download Qwen3-VL-8B-Instruct
- - gguf: https://huggingface.co/unsloth/Qwen3-VL-8B-Instruct-GGUF/tree/main
+## Model files
-## Use original FP8 weights
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Ideogram4 | [Safetensors](https://huggingface.co/ideogram-ai/ideogram-4-fp8/tree/main/transformer) | `--diffusion-model` | Required |
+| Ideogram4 uncond | [Safetensors](https://huggingface.co/ideogram-ai/ideogram-4-fp8/tree/main/unconditional_transformer) | `--uncond-diffusion-model` | Required |
+| vae | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.2-dev/tree/main) | `--vae` | Use matching VAE |
+| Qwen3-VL-8B-Instruct | [GGUF](https://huggingface.co/unsloth/Qwen3-VL-8B-Instruct-GGUF/tree/main) | `--llm` | Use matching text encoder |
+
+### Use original FP8 weights
The original Ideogram4 FP8 safetensors can be loaded directly. FP8 tensors stay
at one byte per element in RAM and VRAM. Backends that cannot multiply FP8
@@ -24,32 +24,120 @@ instead (two bytes per element in RAM and VRAM).
Use `ideogram4_fp8.safetensors` and `ideogram4_uncond_fp8.safetensors` directly
with `--diffusion-model` and `--uncond-diffusion-model`, respectively.
-## Optional conversion for quantization
+### Optional conversion
+
+Run executable conversion examples from the build directory using the
+[shared path and shell conventions](README.md#example-conventions).
+
+#### Optional conversion for quantization
The following conversion is only needed when creating a quantized GGUF model.
fp8 scale -> bf16
+**Windows (PowerShell)**
+
+```powershell
+python .convert_fp8_scale_to_bf16.py --input .ideogram4_fp8.safetensors --output ideogram4_bf16.safetensors
+python .convert_fp8_scale_to_bf16.py --input .ideogram4_uncond_fp8.safetensors --output ideogram4_uncond_bf16.safetensors
```
-python .\convert_fp8_scale_to_bf16.py --input .\ideogram4_fp8.safetensors --output ideogram4_bf16.safetensors
-python .\convert_fp8_scale_to_bf16.py --input .\ideogram4_uncond_fp8.safetensors --output ideogram4_uncond_bf16.safetensors
+
+**Linux/macOS**
+
+```sh
+python .convert_fp8_scale_to_bf16.py --input .ideogram4_fp8.safetensors --output ideogram4_bf16.safetensors
+python .convert_fp8_scale_to_bf16.py --input .ideogram4_uncond_fp8.safetensors --output ideogram4_uncond_bf16.safetensors
```
bf16 -> q8
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M convert `
+ -m ..\models\ideogram4_bf16.safetensors `
+ --tensor-type-rules "^layers.*adaln_modulation.*weight=q8_0,layers.*attention.o.*weight=q8_0,layers.*attention.qkv.*weight=q8_0,layers.*feed_forward.*weight=q8_0" `
+ -o ideogram4-Q8_0.gguf `
+ -v
+
+.\bin\Release\sd-cli.exe `
+ -M convert `
+ -m ..\models\ideogram4_uncond_bf16.safetensors `
+ --tensor-type-rules "^layers.*adaln_modulation.*weight=q8_0,layers.*attention.o.*weight=q8_0,layers.*attention.qkv.*weight=q8_0,layers.*feed_forward.*weight=q8_0" `
+ -o ideogram4_uncond-Q8_0.gguf `
+ -v
```
-.\bin\Release\sd-cli.exe -M convert -m ideogram4_bf16.safetensors -o ideogram4-Q8_0.gguf --tensor-type-rules "^layers.*adaln_modulation.*weight=q8_0,layers.*attention.o.*weight=q8_0,layers.*attention.qkv.*weight=q8_0,layers.*feed_forward.*weight=q8_0" -v
-.\bin\Release\sd-cli.exe -M convert -m ideogram4_uncond_bf16.safetensors -o ideogram4_uncond-Q8_0.gguf --tensor-type-rules "^layers.*adaln_modulation.*weight=q8_0,layers.*attention.o.*weight=q8_0,layers.*attention.qkv.*weight=q8_0,layers.*feed_forward.*weight=q8_0" -v
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M convert \
+ -m ../models/ideogram4_bf16.safetensors \
+ --tensor-type-rules "^layers.*adaln_modulation.*weight=q8_0,layers.*attention.o.*weight=q8_0,layers.*attention.qkv.*weight=q8_0,layers.*feed_forward.*weight=q8_0" \
+ -o ideogram4-Q8_0.gguf \
+ -v
+
+./bin/sd-cli \
+ -M convert \
+ -m ../models/ideogram4_uncond_bf16.safetensors \
+ --tensor-type-rules "^layers.*adaln_modulation.*weight=q8_0,layers.*attention.o.*weight=q8_0,layers.*attention.qkv.*weight=q8_0,layers.*feed_forward.*weight=q8_0" \
+ -o ideogram4_uncond-Q8_0.gguf \
+ -v
```
If you want lower VRAM usage, you can change the quantization from q8_0 to a lower-level quantization, such as q4_0.
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Ideogram 4 (`ideogram4`) | `diffusion_model`, `uncond_diffusion_model`, `llm`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\ideogram4-Q8_0.gguf `
+ --uncond-diffusion-model ..\models\diffusion_models\ideogram4_uncond-Q8_0.gguf `
+ --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ -p "{`"high_level_description`":`"A square 1024 x 1024 luxury fashion magazine cover featuring exactly one short chubby fluffy cat as the main model. The cat sits on a soft ivory studio floor, facing the viewer with a stylish calm expression, wearing tiny black sunglasses, a red silk scarf, and a small gold collar charm. In front of the cat on the floor is a wide horizontal luxury nameplate that clearly reads ideogram4.cpp. The whole design feels premium, fashionable, clean, and editorial.`",`"style_description`":{`"aesthetics`":`"luxury fashion magazine cover, high-end pet couture campaign, minimalist editorial design, elegant studio photography, soft paper texture, refined typography, fashionable and polished`",`"lighting`":`"Soft diffused studio lighting, gentle spotlight on the cat, subtle floor shadow, warm ivory highlights, clean separation between subject and background`",`"photo`":`"high-resolution fashion editorial photography look, front-facing cat portrait, crisp fur details, glossy sunglasses, clear readable nameplate text, shallow depth of field`",`"medium`":`"mixed media fashion photography and premium editorial graphic design`",`"color_palette`":[`"#F4EFE7`",`"#111111`",`"#D8B56D`",`"#B73A3A`",`"#FFFFFF`",`"#8A7A6A`"]},`"compositional_deconstruction`":{`"canvas`":`"Square 1024 x 1024 canvas with a normal upright orientation. Do not rotate the poster or any text. Use a clean fashion magazine cover layout.`",`"background`":`"Warm ivory studio backdrop with subtle paper grain, a soft spotlight gradient, faint floor shadow, and a few minimal gold editorial lines. The background is spacious, premium, and uncluttered.`",`"layout`":`"Top center has a small elegant headline. Center area features one cat as the main fashion model. Lower foreground has a wide horizontal luxury nameplate placed on the floor in front of the cat. Bottom center has a small footer. All text is horizontal, upright, and readable left to right.`",`"elements`":[{`"type`":`"text`",`"desc`":`"Top center headline reading LOOK WHAT I FOUND in a refined high-fashion serif font. The headline is horizontal, centered, elegant, and secondary to the nameplate text.`"},{`"type`":`"obj`",`"desc`":`"Exactly one short chubby fluffy cat sitting in the center like a luxury fashion model. The cat has a large round head, compact body, short legs, soft detailed fur, expressive eyes, and a calm confident pose. The cat is cute and rounded, not tall, not stretched, not duplicated.`"},{`"type`":`"obj`",`"desc`":`"Tiny glossy black sunglasses worn naturally by the cat, slightly oversized but still showing the cat face clearly. The sunglasses add a chic fashion-editorial attitude.`"},{`"type`":`"obj`",`"desc`":`"A red silk scarf tied neatly around the cat neck, with soft folds and a couture feeling. The scarf must not cover the cat face or the nameplate.`"},{`"type`":`"obj`",`"desc`":`"A small gold collar charm or fashion accessory under the scarf, subtle and premium, adding a luxury campaign detail.`"},{`"type`":`"obj`",`"desc`":`"In the lower foreground, place a wide horizontal luxury nameplate on the floor in front of the cat. The nameplate is low, flat, landscape-oriented, much wider than tall, like a fashion show seat card or premium display plaque. It is centered, front-facing, level, and fully visible. It must not become vertical, tall, standing, rotated, or side-facing.`"},{`"type`":`"text`",`"desc`":`"Print the exact text ideogram4.cpp only on the wide horizontal nameplate. Use clean bold black lettering, perfectly spelled, lowercase, with the number 4 and .cpp extension. The text must fit completely inside the nameplate, stay horizontal, and be readable from left to right.`"},{`"type`":`"obj`",`"desc`":`"Add sparse premium editorial accents around the edges: thin gold lines, small code brackets, tiny cursor marks, subtle dots, and minimal geometric details. No extra cats, no stickers, no animal faces, no busy decorations.`"},{`"type`":`"text`",`"desc`":`"Bottom center footer reading tiny paws, big compile energy in a small refined monospace or editorial font. The footer is horizontal, centered, understated, and much smaller than the nameplate text.`"}]}}" `
+ -H 1024 `
+ -W 1024 `
+ --offload-to-cpu `
+ -v
+```
-## Examples
+**Linux/macOS**
```sh
-.\bin\Release\sd-cli.exe --diffusion-model ideogram4-Q8_0.gguf --uncond-diffusion-model ideogram4_uncond-Q8_0.gguf --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf --vae ..\models\vae\flux2_ae.safetensors -p '{"high_level_description":"A square 1024 x 1024 luxury fashion magazine cover featuring exactly one short chubby fluffy cat as the main model. The cat sits on a soft ivory studio floor, facing the viewer with a stylish calm expression, wearing tiny black sunglasses, a red silk scarf, and a small gold collar charm. In front of the cat on the floor is a wide horizontal luxury nameplate that clearly reads ideogram4.cpp. The whole design feels premium, fashionable, clean, and editorial.","style_description":{"aesthetics":"luxury fashion magazine cover, high-end pet couture campaign, minimalist editorial design, elegant studio photography, soft paper texture, refined typography, fashionable and polished","lighting":"Soft diffused studio lighting, gentle spotlight on the cat, subtle floor shadow, warm ivory highlights, clean separation between subject and background","photo":"high-resolution fashion editorial photography look, front-facing cat portrait, crisp fur details, glossy sunglasses, clear readable nameplate text, shallow depth of field","medium":"mixed media fashion photography and premium editorial graphic design","color_palette":["#F4EFE7","#111111","#D8B56D","#B73A3A","#FFFFFF","#8A7A6A"]},"compositional_deconstruction":{"canvas":"Square 1024 x 1024 canvas with a normal upright orientation. Do not rotate the poster or any text. Use a clean fashion magazine cover layout.","background":"Warm ivory studio backdrop with subtle paper grain, a soft spotlight gradient, faint floor shadow, and a few minimal gold editorial lines. The background is spacious, premium, and uncluttered.","layout":"Top center has a small elegant headline. Center area features one cat as the main fashion model. Lower foreground has a wide horizontal luxury nameplate placed on the floor in front of the cat. Bottom center has a small footer. All text is horizontal, upright, and readable left to right.","elements":[{"type":"text","desc":"Top center headline reading LOOK WHAT I FOUND in a refined high-fashion serif font. The headline is horizontal, centered, elegant, and secondary to the nameplate text."},{"type":"obj","desc":"Exactly one short chubby fluffy cat sitting in the center like a luxury fashion model. The cat has a large round head, compact body, short legs, soft detailed fur, expressive eyes, and a calm confident pose. The cat is cute and rounded, not tall, not stretched, not duplicated."},{"type":"obj","desc":"Tiny glossy black sunglasses worn naturally by the cat, slightly oversized but still showing the cat face clearly. The sunglasses add a chic fashion-editorial attitude."},{"type":"obj","desc":"A red silk scarf tied neatly around the cat neck, with soft folds and a couture feeling. The scarf must not cover the cat face or the nameplate."},{"type":"obj","desc":"A small gold collar charm or fashion accessory under the scarf, subtle and premium, adding a luxury campaign detail."},{"type":"obj","desc":"In the lower foreground, place a wide horizontal luxury nameplate on the floor in front of the cat. The nameplate is low, flat, landscape-oriented, much wider than tall, like a fashion show seat card or premium display plaque. It is centered, front-facing, level, and fully visible. It must not become vertical, tall, standing, rotated, or side-facing."},{"type":"text","desc":"Print the exact text ideogram4.cpp only on the wide horizontal nameplate. Use clean bold black lettering, perfectly spelled, lowercase, with the number 4 and .cpp extension. The text must fit completely inside the nameplate, stay horizontal, and be readable from left to right."},{"type":"obj","desc":"Add sparse premium editorial accents around the edges: thin gold lines, small code brackets, tiny cursor marks, subtle dots, and minimal geometric details. No extra cats, no stickers, no animal faces, no busy decorations."},{"type":"text","desc":"Bottom center footer reading tiny paws, big compile energy in a small refined monospace or editorial font. The footer is horizontal, centered, understated, and much smaller than the nameplate text."}]}}' -v --offload-to-cpu -H 1024 -W 1024
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/ideogram4-Q8_0.gguf \
+ --uncond-diffusion-model ../models/diffusion_models/ideogram4_uncond-Q8_0.gguf \
+ --llm ../models/text_encoders/Qwen3VL-8B-Instruct-Q4_K_M.gguf \
+ --vae ../models/vae/flux2_ae.safetensors \
+ -p "{\"high_level_description\":\"A square 1024 x 1024 luxury fashion magazine cover featuring exactly one short chubby fluffy cat as the main model. The cat sits on a soft ivory studio floor, facing the viewer with a stylish calm expression, wearing tiny black sunglasses, a red silk scarf, and a small gold collar charm. In front of the cat on the floor is a wide horizontal luxury nameplate that clearly reads ideogram4.cpp. The whole design feels premium, fashionable, clean, and editorial.\",\"style_description\":{\"aesthetics\":\"luxury fashion magazine cover, high-end pet couture campaign, minimalist editorial design, elegant studio photography, soft paper texture, refined typography, fashionable and polished\",\"lighting\":\"Soft diffused studio lighting, gentle spotlight on the cat, subtle floor shadow, warm ivory highlights, clean separation between subject and background\",\"photo\":\"high-resolution fashion editorial photography look, front-facing cat portrait, crisp fur details, glossy sunglasses, clear readable nameplate text, shallow depth of field\",\"medium\":\"mixed media fashion photography and premium editorial graphic design\",\"color_palette\":[\"#F4EFE7\",\"#111111\",\"#D8B56D\",\"#B73A3A\",\"#FFFFFF\",\"#8A7A6A\"]},\"compositional_deconstruction\":{\"canvas\":\"Square 1024 x 1024 canvas with a normal upright orientation. Do not rotate the poster or any text. Use a clean fashion magazine cover layout.\",\"background\":\"Warm ivory studio backdrop with subtle paper grain, a soft spotlight gradient, faint floor shadow, and a few minimal gold editorial lines. The background is spacious, premium, and uncluttered.\",\"layout\":\"Top center has a small elegant headline. Center area features one cat as the main fashion model. Lower foreground has a wide horizontal luxury nameplate placed on the floor in front of the cat. Bottom center has a small footer. All text is horizontal, upright, and readable left to right.\",\"elements\":[{\"type\":\"text\",\"desc\":\"Top center headline reading LOOK WHAT I FOUND in a refined high-fashion serif font. The headline is horizontal, centered, elegant, and secondary to the nameplate text.\"},{\"type\":\"obj\",\"desc\":\"Exactly one short chubby fluffy cat sitting in the center like a luxury fashion model. The cat has a large round head, compact body, short legs, soft detailed fur, expressive eyes, and a calm confident pose. The cat is cute and rounded, not tall, not stretched, not duplicated.\"},{\"type\":\"obj\",\"desc\":\"Tiny glossy black sunglasses worn naturally by the cat, slightly oversized but still showing the cat face clearly. The sunglasses add a chic fashion-editorial attitude.\"},{\"type\":\"obj\",\"desc\":\"A red silk scarf tied neatly around the cat neck, with soft folds and a couture feeling. The scarf must not cover the cat face or the nameplate.\"},{\"type\":\"obj\",\"desc\":\"A small gold collar charm or fashion accessory under the scarf, subtle and premium, adding a luxury campaign detail.\"},{\"type\":\"obj\",\"desc\":\"In the lower foreground, place a wide horizontal luxury nameplate on the floor in front of the cat. The nameplate is low, flat, landscape-oriented, much wider than tall, like a fashion show seat card or premium display plaque. It is centered, front-facing, level, and fully visible. It must not become vertical, tall, standing, rotated, or side-facing.\"},{\"type\":\"text\",\"desc\":\"Print the exact text ideogram4.cpp only on the wide horizontal nameplate. Use clean bold black lettering, perfectly spelled, lowercase, with the number 4 and .cpp extension. The text must fit completely inside the nameplate, stay horizontal, and be readable from left to right.\"},{\"type\":\"obj\",\"desc\":\"Add sparse premium editorial accents around the edges: thin gold lines, small code brackets, tiny cursor marks, subtle dots, and minimal geometric details. No extra cats, no stickers, no animal faces, no busy decorations.\"},{\"type\":\"text\",\"desc\":\"Bottom center footer reading tiny paws, big compile energy in a small refined monospace or editorial font. The footer is horizontal, centered, understated, and much smaller than the nameplate text.\"}]}}" \
+ -H 1024 \
+ -W 1024 \
+ --offload-to-cpu \
+ -v
```
<img alt="ideogram4 image example" src="../../assets/ideogram4/example.png" />
diff --git a/docs/models/ip_adapter.md b/docs/models/ip_adapter.md
index 27f9ae6..854ed88 100644
--- a/docs/models/ip_adapter.md
+++ b/docs/models/ip_adapter.md
@@ -1,87 +1,223 @@
# IP-Adapter
-stable-diffusion.cpp supports [IP-Adapter](https://github.com/tencent-ailab/IP-Adapter)
-image-prompt conditioning for SD 1.5 and SDXL. Given a reference image,
-IP-Adapter transfers the subject and appearance of that image into the
-generation, alongside the text prompt.
-
-IP-Adapter encodes the reference image with a CLIP-Vision (ViT-H/14)
-encoder, projects the embedding into a few image tokens, and injects them
-through a decoupled cross-attention added to every attn2 layer of the
-UNet. It composes with Control Net, so a reference image (appearance) and
-an OpenPose hint (pose) can be combined in a single generation.
-
-Both the classic adapters and the higher-fidelity **Plus** adapters are
-supported; see [Plus variants](#plus-variants) below. The variant is
-detected from the weight file, so the same options work for both.
-
-## Required weights
-
-1. A base SD 1.5 or SDXL model.
-2. A CLIP-Vision (ViT-H/14) image encoder, passed with `--clip_vision`
- (for example `clip_vision_h.safetensors`).
-3. An IP-Adapter weight file, passed with `--ip-adapter`. The `vit-h`
- variants reuse the same ViT-H encoder as above. From
- [h94/IP-Adapter](https://huggingface.co/h94/IP-Adapter):
- - SD 1.5: `models/ip-adapter_sd15.safetensors`
- - SDXL: `sdxl_models/ip-adapter_sdxl_vit-h.safetensors`
- - SD 1.5 Plus: `models/ip-adapter-plus_sd15.safetensors`
- - SDXL Plus: `sdxl_models/ip-adapter-plus_sdxl_vit-h.safetensors`
-
- The Plus files (`ip-adapter-plus_*`) are used exactly like the classic
- ones; see [Plus variants](#plus-variants).
-
-## Options
-
-- `--ip-adapter <path>` path to the IP-Adapter weight file.
-- `--ip-adapter-image <path>` path to the reference image.
-- `--ip-adapter-strength <float>` strength of the IP-Adapter injection
- (default 1.0). Lower values let the text prompt dominate; 0.6 to 0.8 is
- a good starting range.
-
-## Example (SD 1.5)
-
-```
-sd-cli -m ..\models\sd_v1.5.safetensors --clip_vision ..\models\clip_vision_h.safetensors --ip-adapter ..\models\ip-adapter_sd15.safetensors --ip-adapter-image ..\assets\reference.png --ip-adapter-strength 0.8 -p "a woman, best quality" -n "lowres, bad anatomy" --cfg-scale 7 --steps 30 --sampling-method dpm++2m --scheduler karras -W 512 -H 512
+[IP-Adapter](https://github.com/tencent-ailab/IP-Adapter) uses a reference image
+to guide SD 1.5 or SDXL generation alongside
+the text prompt. Classic and Plus adapters are supported, including combination
+with Control Net.
+
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Base checkpoint | [SD 1.5 or SDXL](sd.md) | `-m` / `--model` | Required; match adapter family |
+| CLIP Vision H | `clip_vision_h.safetensors` from [IP-Adapter](https://huggingface.co/h94/IP-Adapter) | `--clip_vision` | Required; ViT-H/14 |
+| SD 1.5 adapter | [`models/ip-adapter_sd15.safetensors`](https://huggingface.co/h94/IP-Adapter) | `--ip-adapter` | For SD 1.5 |
+| SDXL adapter | [`sdxl_models/ip-adapter_sdxl_vit-h.safetensors`](https://huggingface.co/h94/IP-Adapter) | `--ip-adapter` | For SDXL |
+| SD 1.5 Plus | [`models/ip-adapter-plus_sd15.safetensors`](https://huggingface.co/h94/IP-Adapter) | `--ip-adapter` | Alternative for SD 1.5 |
+| SDXL Plus | [`sdxl_models/ip-adapter-plus_sdxl_vit-h.safetensors`](https://huggingface.co/h94/IP-Adapter) | `--ip-adapter` | Alternative for SDXL |
+
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| SD 1.5 IP-Adapter / Plus (`sd1-ip-adapter`) | `model`, `clip_vision`, `ip_adapter`, `vae`, `tae` |
+| SDXL IP-Adapter / Plus (`sdxl-ip-adapter`) | `model`, `clip_vision`, `ip_adapter`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Example (SD 1.5)
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\sd_v1.5.safetensors `
+ --clip_vision ..\models\clip_vision\clip_vision_h.safetensors `
+ --ip-adapter ..\models\ipadapter\ip-adapter_sd15.safetensors `
+ --ip-adapter-image ..\inputs\reference.png `
+ -p "a woman, best quality" `
+ -n "lowres, bad anatomy" `
+ --cfg-scale 7 `
+ --steps 30 `
+ --sampling-method dpm++2m `
+ --scheduler karras `
+ -W 512 `
+ -H 512 `
+ --ip-adapter-strength 0.8
```
-## Example (SDXL)
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -m ../models/checkpoints/sd_v1.5.safetensors \
+ --clip_vision ../models/clip_vision/clip_vision_h.safetensors \
+ --ip-adapter ../models/ipadapter/ip-adapter_sd15.safetensors \
+ --ip-adapter-image ../inputs/reference.png \
+ -p "a woman, best quality" \
+ -n "lowres, bad anatomy" \
+ --cfg-scale 7 \
+ --steps 30 \
+ --sampling-method dpm++2m \
+ --scheduler karras \
+ -W 512 \
+ -H 512 \
+ --ip-adapter-strength 0.8
+```
+#### Example (SDXL)
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\sdxl.safetensors `
+ --clip_vision ..\models\clip_vision\clip_vision_h.safetensors `
+ --ip-adapter ..\models\ipadapter\ip-adapter_sdxl_vit-h.safetensors `
+ --ip-adapter-image ..\inputs\reference.png `
+ -p "a woman, best quality" `
+ -n "lowres, bad anatomy" `
+ --cfg-scale 6 `
+ --steps 25 `
+ --sampling-method dpm++2m `
+ --scheduler karras `
+ -W 1024 `
+ -H 1024 `
+ --ip-adapter-strength 0.8 `
+ --vae-tiling
```
-sd-cli -m ..\models\sdxl.safetensors --clip_vision ..\models\clip_vision_h.safetensors --ip-adapter ..\models\ip-adapter_sdxl_vit-h.safetensors --ip-adapter-image ..\assets\reference.png --ip-adapter-strength 0.8 -p "a woman, best quality" -n "lowres, bad anatomy" --cfg-scale 6 --steps 25 --sampling-method dpm++2m --scheduler karras -W 1024 -H 1024 --vae-tiling
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -m ../models/checkpoints/sdxl.safetensors \
+ --clip_vision ../models/clip_vision/clip_vision_h.safetensors \
+ --ip-adapter ../models/ipadapter/ip-adapter_sdxl_vit-h.safetensors \
+ --ip-adapter-image ../inputs/reference.png \
+ -p "a woman, best quality" \
+ -n "lowres, bad anatomy" \
+ --cfg-scale 6 \
+ --steps 25 \
+ --sampling-method dpm++2m \
+ --scheduler karras \
+ -W 1024 \
+ -H 1024 \
+ --ip-adapter-strength 0.8 \
+ --vae-tiling
```
The SDXL VAE decode at 1024x1024 is memory heavy; add `--vae-tiling` (and
`--offload-to-cpu`) on GPUs with limited VRAM.
-## Plus variants
-
-The Plus adapters (`ip-adapter-plus_sd15`, `ip-adapter-plus_sdxl_vit-h`)
-replace the small linear image projection with a Resampler (a
-Perceiver-style module with learned latent queries). Instead of pooling the
-CLIP-Vision output into one vector, the Resampler attends over the full grid
-of penultimate CLIP-Vision hidden states and emits more image tokens (16
-instead of 4). The result transfers finer detail and layout from the
-reference, at a small extra cost in the image-projection step.
-
-No extra flags are needed. The variant is detected from the weight file (the
-Resampler's `image_proj.latents` tensor), and every Resampler dimension is
-read from the tensor shapes, so the same `--ip-adapter`,
-`--ip-adapter-image`, and `--ip-adapter-strength` options apply. Plus
-composes with Control Net in the same way as the classic adapters.
-
+#### Plus variants
+
+Use the Plus weights matching your base model. The same IP-Adapter options
+apply; no extra flag is needed. Plus can also be combined with Control Net.
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\sd_v1.5.safetensors `
+ --clip_vision ..\models\clip_vision\clip_vision_h.safetensors `
+ --ip-adapter ..\models\ipadapter\ip-adapter-plus_sd15.safetensors `
+ --ip-adapter-image ..\inputs\reference.png `
+ -p "a woman, best quality" `
+ -n "lowres, bad anatomy" `
+ --cfg-scale 7 `
+ --steps 30 `
+ --sampling-method dpm++2m `
+ --scheduler karras `
+ -W 512 `
+ -H 512 `
+ --ip-adapter-strength 0.8
```
-sd-cli -m ..\models\sd_v1.5.safetensors --clip_vision ..\models\clip_vision_h.safetensors --ip-adapter ..\models\ip-adapter-plus_sd15.safetensors --ip-adapter-image ..\assets\reference.png --ip-adapter-strength 0.8 -p "a woman, best quality" -n "lowres, bad anatomy" --cfg-scale 7 --steps 30 --sampling-method dpm++2m --scheduler karras -W 512 -H 512
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -m ../models/checkpoints/sd_v1.5.safetensors \
+ --clip_vision ../models/clip_vision/clip_vision_h.safetensors \
+ --ip-adapter ../models/ipadapter/ip-adapter-plus_sd15.safetensors \
+ --ip-adapter-image ../inputs/reference.png \
+ -p "a woman, best quality" \
+ -n "lowres, bad anatomy" \
+ --cfg-scale 7 \
+ --steps 30 \
+ --sampling-method dpm++2m \
+ --scheduler karras \
+ -W 512 \
+ -H 512 \
+ --ip-adapter-strength 0.8
```
The startup log line `IP-Adapter: 16 image tokens` (versus `4` for the
classic adapters) confirms a Plus file was loaded.
-## Combining with Control Net
+#### Combining with Control Net
Add the usual Control Net options to keep the reference appearance while
controlling the pose:
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\sdxl.safetensors `
+ --clip_vision ..\models\clip_vision\clip_vision_h.safetensors `
+ --ip-adapter ..\models\ipadapter\ip-adapter_sdxl_vit-h.safetensors `
+ --control-net ..\models\controlnet\OpenPoseXL2.safetensors `
+ --ip-adapter-image ..\inputs\character.png `
+ --control-image ..\inputs\pose.png `
+ -p "a character, side view" `
+ --cfg-scale 6 `
+ --steps 25 `
+ -W 1024 `
+ -H 1024 `
+ --ip-adapter-strength 0.9 `
+ --control-strength 0.8 `
+ --vae-tiling
```
-sd-cli -m ..\models\sdxl.safetensors --clip_vision ..\models\clip_vision_h.safetensors --ip-adapter ..\models\ip-adapter_sdxl_vit-h.safetensors --ip-adapter-image ..\assets\character.png --ip-adapter-strength 0.9 --control-net ..\models\OpenPoseXL2.safetensors --control-image ..\assets\pose.png --control-strength 0.8 -p "a character, side view" --cfg-scale 6 --steps 25 -W 1024 -H 1024 --vae-tiling
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -m ../models/checkpoints/sdxl.safetensors \
+ --clip_vision ../models/clip_vision/clip_vision_h.safetensors \
+ --ip-adapter ../models/ipadapter/ip-adapter_sdxl_vit-h.safetensors \
+ --control-net ../models/controlnet/OpenPoseXL2.safetensors \
+ --ip-adapter-image ../inputs/character.png \
+ --control-image ../inputs/pose.png \
+ -p "a character, side view" \
+ --cfg-scale 6 \
+ --steps 25 \
+ -W 1024 \
+ -H 1024 \
+ --ip-adapter-strength 0.9 \
+ --control-strength 0.8 \
+ --vae-tiling
```
+
+## Options
+
+- `--ip-adapter <path>` path to the IP-Adapter weight file.
+- `--ip-adapter-image <path>` path to the reference image.
+- `--ip-adapter-strength <float>` strength of the IP-Adapter injection
+ (default 1.0). Lower values let the text prompt dominate; 0.6 to 0.8 is
+ a good starting range.
diff --git a/docs/models/iris.md b/docs/models/iris.md
index c279a13..643b0d2 100644
--- a/docs/models/iris.md
+++ b/docs/models/iris.md
@@ -1,24 +1,62 @@
-# How to Use
+# Iris-3B
Iris-3B generates images directly in pixel space and uses Qwen3-VL-4B-Instruct as the text encoder. No VAE is required.
-## Download weights
+## Model files
-- Download Iris-3B
- - safetensors: https://huggingface.co/speridlabs/iris-3b/tree/main (`model.safetensors` in the root directory)
-- Download Qwen3-VL-4B-Instruct
- - safetensors: https://huggingface.co/Comfy-Org/Krea-2/tree/main/text_encoders
- - gguf: https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct-GGUF/tree/main
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Iris-3B | [Safetensors](https://huggingface.co/speridlabs/iris-3b/tree/main) (`model.safetensors` in the root directory) | `--diffusion-model` | Required |
+| Qwen3-VL-4B-Instruct | [Safetensors](https://huggingface.co/Comfy-Org/Krea-2/tree/main/text_encoders)<br>[GGUF](https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct-GGUF/tree/main) | `--llm` | Use matching text encoder |
-## Examples
+## Usage
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Iris 3B (`iris-3b`) | `diffusion_model`, `llm` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\iris-3b.safetensors `
+ --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf `
+ -p "a lovely cat" `
+ --cfg-scale 3 `
+ -H 1024 `
+ -W 1024
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\iris-3b.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf -p "a lovely cat" --cfg-scale 3 -H 1024 -W 1024
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/iris-3b.safetensors \
+ --llm ../models/text_encoders/Qwen3-VL-4B-Instruct-Q4_K_M.gguf \
+ -p "a lovely cat" \
+ --cfg-scale 3 \
+ -H 1024 \
+ -W 1024
```
<img width="256" alt="iris-3b example" src="../../assets/iris/example.png" />
-## Notes
+## Notes and limitations
- Width and height must be multiples of 16. Do not pass `--vae`.
- Captions are limited to 300 tokens including the assistant-turn suffix. Positive and negative prompts use the same template.
diff --git a/docs/models/kontext.md b/docs/models/kontext.md
index d150b13..c711f32 100644
--- a/docs/models/kontext.md
+++ b/docs/models/kontext.md
@@ -1,39 +1,108 @@
-# How to Use
+# FLUX.1 Kontext
+
+FLUX.1 Kontext supports reference-image editing using the FLUX.1 VAE, CLIP-L, and T5-XXL.
You can run Kontext using stable-diffusion.cpp with a GPU that has 6GB or even 4GB of VRAM, without needing to offload to RAM.
-## Download weights
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Kontext | If you don't want to do the conversion yourself, download the preconverted gguf model from [FLUX.1-Kontext-dev-GGUF](https://huggingface.co/QuantStack/FLUX.1-Kontext-dev-GGUF)<br>Otherwise, download FLUX.1-Kontext-dev from [Download](https://huggingface.co/black-forest-labs/FLUX.1-Kontext-dev/blob/main/flux1-kontext-dev.safetensors) | `--diffusion-model` | Required |
+| vae | vae from [Download](https://huggingface.co/black-forest-labs/FLUX.1-dev/blob/main/ae.safetensors) | `--vae` | Use matching VAE |
+| clip_l | clip_l from [Download](https://huggingface.co/comfyanonymous/flux_text_encoders/blob/main/clip_l.safetensors) | `--clip_l` | Required |
+| t5xxl | t5xxl from [Download](https://huggingface.co/comfyanonymous/flux_text_encoders/blob/main/t5xxl_fp16.safetensors) | `--t5xxl` | Required |
+
+### Optional conversion
-- Download Kontext
- - If you don't want to do the conversion yourself, download the preconverted gguf model from [FLUX.1-Kontext-dev-GGUF](https://huggingface.co/QuantStack/FLUX.1-Kontext-dev-GGUF)
- - Otherwise, download FLUX.1-Kontext-dev from https://huggingface.co/black-forest-labs/FLUX.1-Kontext-dev/blob/main/flux1-kontext-dev.safetensors
-- Download vae from https://huggingface.co/black-forest-labs/FLUX.1-dev/blob/main/ae.safetensors
-- Download clip_l from https://huggingface.co/comfyanonymous/flux_text_encoders/blob/main/clip_l.safetensors
-- Download t5xxl from https://huggingface.co/comfyanonymous/flux_text_encoders/blob/main/t5xxl_fp16.safetensors
+Run executable conversion examples from the build directory using the
+[shared path and shell conventions](README.md#example-conventions).
-## Convert Kontext weights
+#### Convert Kontext weights
You can download the preconverted gguf weights from [FLUX.1-Kontext-dev-GGUF](https://huggingface.co/QuantStack/FLUX.1-Kontext-dev-GGUF), this way you don't have to do the conversion yourself.
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M convert `
+ -m ..\models\unet\flux1-kontext-dev.safetensors `
+ --type q8_0 `
+ -o ..\models\diffusion_models\flux1-kontext-dev-q8_0.gguf `
+ -v
```
-.\bin\Release\sd-cli.exe -M convert -m ..\models\unet\flux1-kontext-dev.safetensors -o ..\models\flux1-kontext-dev-q8_0.gguf -v --type q8_0
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M convert \
+ -m ../models/unet/flux1-kontext-dev.safetensors \
+ --type q8_0 \
+ -o ../models/diffusion_models/flux1-kontext-dev-q8_0.gguf \
+ -v
```
-## Run
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| FLUX.1 Kontext dev (`flux1-kontext`) | `diffusion_model`, `clip_l`, `t5xxl`, `vae`, `tae` |
-- `--cfg-scale` is recommended to be set to 1.
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+- `--cfg-scale` is recommended to be set to 1.
+
+#### Example
-### Example
For example:
-```
- .\bin\Release\sd-cli.exe -r .\flux1-dev-q8_0.png --diffusion-model ..\models\flux1-kontext-dev-q8_0.gguf --vae ..\models\ae.sft --clip_l ..\models\clip_l.safetensors --t5xxl ..\models\t5xxl_fp16.safetensors -p "change 'flux.cpp' to 'kontext.cpp'" --cfg-scale 1.0 --sampling-method euler -v --clip-on-cpu
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\flux1-kontext-dev-q8_0.gguf `
+ --vae ..\models\vae\ae.sft `
+ --clip_l ..\models\text_encoders\clip_l.safetensors `
+ --t5xxl ..\models\text_encoders\t5xxl_fp16.safetensors `
+ -r .\flux1-dev-q8_0.png `
+ -p "change 'flux.cpp' to 'kontext.cpp'" `
+ --cfg-scale 1.0 `
+ --sampling-method euler `
+ --clip-on-cpu `
+ -v
```
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/flux1-kontext-dev-q8_0.gguf \
+ --vae ../models/vae/ae.sft \
+ --clip_l ../models/text_encoders/clip_l.safetensors \
+ --t5xxl ../models/text_encoders/t5xxl_fp16.safetensors \
+ -r ./flux1-dev-q8_0.png \
+ -p "change 'flux.cpp' to 'kontext.cpp'" \
+ --cfg-scale 1.0 \
+ --sampling-method euler \
+ --clip-on-cpu \
+ -v
+```
| ref_image | prompt | output |
| ---- | ---- |---- |
|  | change 'flux.cpp' to 'kontext.cpp' | |
-
-
-
diff --git a/docs/models/krea2.md b/docs/models/krea2.md
index b49fc67..c636711 100644
--- a/docs/models/krea2.md
+++ b/docs/models/krea2.md
@@ -1,27 +1,62 @@
-# How to Use
+# Krea2
Krea2 uses a Krea2 diffusion transformer, the Wan2.1 VAE, and Qwen3-VL 4B as the LLM text encoder.
-## Download weights
+## Model files
-- Download Krea2 Raw
- - safetensors: https://huggingface.co/krea/Krea-2-Raw/tree/main
- - gguf: https://huggingface.co/realrebelai/KREA-2_GGUFs/tree/main/BASE
-- Download Krea2 Turbo
- - safetensors: https://huggingface.co/krea/Krea-2-Turbo/tree/main
- - gguf: https://huggingface.co/realrebelai/KREA-2_GGUFs/tree/main/TURBO
-- Download vae
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/blob/main/split_files/vae/wan_2.1_vae.safetensors
-- Download Qwen3-VL 4B
- - safetensors: https://huggingface.co/Comfy-Org/Krea-2/tree/main/text_encoders
- - gguf: https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct-GGUF/tree/main
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Krea2 Raw | [Safetensors](https://huggingface.co/krea/Krea-2-Raw/tree/main)<br>[GGUF](https://huggingface.co/realrebelai/KREA-2_GGUFs/tree/main/BASE) | `--diffusion-model` | Choose matching variant |
+| Krea2 Turbo | [Safetensors](https://huggingface.co/krea/Krea-2-Turbo/tree/main)<br>[GGUF](https://huggingface.co/realrebelai/KREA-2_GGUFs/tree/main/TURBO) | `--diffusion-model` | Choose matching variant |
+| vae | [Safetensors](https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/blob/main/split_files/vae/wan_2.1_vae.safetensors) | `--vae` | Use matching VAE |
+| Qwen3-VL 4B | [Safetensors](https://huggingface.co/Comfy-Org/Krea-2/tree/main/text_encoders)<br>[GGUF](https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct-GGUF/tree/main) | `--llm` | Use matching text encoder |
-## Examples
+## Usage
-### Krea2
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Krea 2 Raw (`krea2-raw`) | `diffusion_model`, `llm`, `vae`, `tae` |
+| Krea 2 Turbo (`krea2-turbo`) | `diffusion_model`, `llm`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Krea2
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\Krea-2-Raw-Q8_0.gguf `
+ --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ -p "a lovely cat holding a sign says 'krea2.cpp'" `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\Krea-2-Raw-Q8_0.gguf --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --vae ..\models\vae\wan_2.1_vae.safetensors -p "a lovely cat holding a sign says 'krea2.cpp'" -v --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/Krea-2-Raw-Q8_0.gguf \
+ --llm ../models/text_encoders/Qwen3-VL-4B-Instruct-Q4_K_M.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ -p "a lovely cat holding a sign says 'krea2.cpp'" \
+ --offload-to-cpu \
+ -v
```
<img width="256" alt="Krea2 Raw example" src="../../assets/krea2/example.png" />
diff --git a/docs/models/lcm.md b/docs/models/lcm.md
index f12fa5b..90330d2 100644
--- a/docs/models/lcm.md
+++ b/docs/models/lcm.md
@@ -1,15 +1,76 @@
-## LCM/LCM-LoRA
+# LCM and LCM-LoRA
-- Download LCM-LoRA form https://huggingface.co/latent-consistency/lcm-lora-sdv1-5
-- Specify LCM-LoRA by adding `<lora:lcm-lora-sdv1-5:1>` to prompt
-- It's advisable to set `--cfg-scale` to `1.0` instead of the default `7.0`. For `--steps`, a range of `2-8` steps is recommended. For `--sampling-method`, `lcm`/`euler_a` is recommended.
+LCM checkpoints and LCM-LoRAs support generation with a small number of steps.
+The example below applies an LCM-LoRA to SD 1.5.
-Here's a simple example:
+## Model files
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Base model | [Stable Diffusion 1.5 checkpoint](sd.md) | `-m` / `--model` | Required for the SD 1.5 LoRA example |
+| LCM-LoRA | [LCM-LoRA SD 1.5](https://huggingface.co/latent-consistency/lcm-lora-sdv1-5) | `--lora-model-dir` and prompt | Match the LoRA to the base model |
+
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| SD 1.x (`sd1-checkpoint`) | `model`, `vae`, `tae` |
+| SDXL (`sdxl-checkpoint`) | `model`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+Select the matching LCM checkpoint or apply a compatible LCM-LoRA, then set the
+sampling method, CFG, and steps for that model.
+
+### CLI
+
+#### LCM-LoRA with SD 1.5
+
+Add `<lora:lcm-lora-sdv1-5:1>` to the prompt:
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\v1-5-pruned-emaonly.safetensors `
+ --lora-model-dir ..\models\loras `
+ -p "a lovely cat<lora:lcm-lora-sdv1-5:1>" `
+ --steps 4 `
+ --cfg-scale 1 `
+ -v
```
-./bin/sd-cli -m ../models/v1-5-pruned-emaonly.safetensors -p "a lovely cat<lora:lcm-lora-sdv1-5:1>" --steps 4 --lora-model-dir ../models -v --cfg-scale 1
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -m ../models/checkpoints/v1-5-pruned-emaonly.safetensors \
+ --lora-model-dir ../models/loras \
+ -p "a lovely cat<lora:lcm-lora-sdv1-5:1>" \
+ --steps 4 \
+ --cfg-scale 1 \
+ -v
```
+#### LCM-LoRA comparison
+
| without LCM-LoRA (--cfg-scale 7) | with LCM-LoRA (--cfg-scale 1) |
| ---- |---- |
-|  | |
\ No newline at end of file
+|  | |
+
+## Options
+
+Use `--cfg-scale 1.0` and 2-8 steps for the LCM-LoRA workflow. The original
+example uses `euler_a`; `lcm` sampling is also supported. See
+[sampling methods and schedulers](../guides/sampling.md) for their defaults.
diff --git a/docs/models/lens.md b/docs/models/lens.md
index c7aac77..42708eb 100644
--- a/docs/models/lens.md
+++ b/docs/models/lens.md
@@ -1,36 +1,99 @@
-# How to Use
+# Lens
Lens uses a Lens diffusion transformer, the FLUX.2 VAE, and GPT-OSS-20B as the LLM text encoder.
-## Download weights
+## Model files
-- Download Lens
- - safetensors: https://huggingface.co/Comfy-Org/Lens/tree/main/diffusion_models
-- Download Lens Turbo
- - safetensors: https://huggingface.co/Comfy-Org/Lens/tree/main/diffusion_models
-- Download vae
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.2-dev/tree/main
-- Download GPT-OSS-20B
- - gguf: https://huggingface.co/unsloth/gpt-oss-20b-GGUF/tree/main
-- Download GPT-OSS-20B tokenizer.json
- - https://huggingface.co/openai/gpt-oss-20b/tree/main
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Lens | [Safetensors](https://huggingface.co/Comfy-Org/Lens/tree/main/diffusion_models) | `--diffusion-model` | Choose matching variant |
+| Lens Turbo | [Safetensors](https://huggingface.co/Comfy-Org/Lens/tree/main/diffusion_models) | `--diffusion-model` | Choose matching variant |
+| vae | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.2-dev/tree/main) | `--vae` | Use matching VAE |
+| GPT-OSS-20B | [GGUF](https://huggingface.co/unsloth/gpt-oss-20b-GGUF/tree/main) | `--llm` | Use matching text encoder |
+| GPT-OSS-20B tokenizer.json | [Download](https://huggingface.co/openai/gpt-oss-20b/tree/main) | `--tokenizer` | Required; match text encoder |
Lens and Lens Turbo require an external GPT-OSS `tokenizer.json` matching the text encoder checkpoint. Save it as `tokenizer_gpt_oss.json` and pass it with `--tokenizer`; the tokenizer is not embedded in sd.cpp. See [JSON tokenizers](../guides/tokenizers.md) for CLI and C API usage.
-## Examples
+## Usage
-### Lens
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| LENS (`lens`) | `diffusion_model`, `llm`, `tokenizer`, `vae`, `tae` |
+| LENS Turbo (`lens-turbo`) | `diffusion_model`, `llm`, `tokenizer`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Lens
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\lens_bf16.safetensors `
+ --llm ..\models\text_encoders\gpt-oss-20b-UD-Q8_K_XL.gguf `
+ --tokenizer ..\models\tokenizers\tokenizer_gpt_oss.json `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ -p "A crystal dragon soaring through an aurora borealis sky, its entire body made of transparent faceted crystal refracting the green and purple aurora light into rainbow spectra, ice particles trailing from its wings, high fantasy digital art" `
+ --cfg-scale 5.0 `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\lens_bf16.safetensors --llm "..\models\text_encoders\gpt-oss-20b-UD-Q8_K_XL.gguf" --tokenizer ..\models\tokenizers\tokenizer_gpt_oss.json --vae ..\models\vae\flux2_ae.safetensors --cfg-scale 5.0 -p "A crystal dragon soaring through an aurora borealis sky, its entire body made of transparent faceted crystal refracting the green and purple aurora light into rainbow spectra, ice particles trailing from its wings, high fantasy digital art" -v
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/lens_bf16.safetensors \
+ --llm ../models/text_encoders/gpt-oss-20b-UD-Q8_K_XL.gguf \
+ --tokenizer ../models/tokenizers/tokenizer_gpt_oss.json \
+ --vae ../models/vae/flux2_ae.safetensors \
+ -p "A crystal dragon soaring through an aurora borealis sky, its entire body made of transparent faceted crystal refracting the green and purple aurora light into rainbow spectra, ice particles trailing from its wings, high fantasy digital art" \
+ --cfg-scale 5.0 \
+ -v
```
<img width="256" alt="Lens example" src="../../assets/lens/example.png" />
-### Lens Turbo
+#### Lens Turbo
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\lens_turbo_bf16.safetensors `
+ --llm ..\models\text_encoders\gpt-oss-20b-UD-Q8_K_XL.gguf `
+ --tokenizer ..\models\tokenizers\tokenizer_gpt_oss.json `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ -p "A crystal dragon soaring through an aurora borealis sky, its entire body made of transparent faceted crystal refracting the green and purple aurora light into rainbow spectra, ice particles trailing from its wings, high fantasy digital art" `
+ --cfg-scale 1.0 `
+ --steps 4 `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\lens_turbo_bf16.safetensors --llm "..\models\text_encoders\gpt-oss-20b-UD-Q8_K_XL.gguf" --tokenizer ..\models\tokenizers\tokenizer_gpt_oss.json --vae ..\models\vae\flux2_ae.safetensors --cfg-scale 1.0 -p "A crystal dragon soaring through an aurora borealis sky, its entire body made of transparent faceted crystal refracting the green and purple aurora light into rainbow spectra, ice particles trailing from its wings, high fantasy digital art" -v --steps 4
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/lens_turbo_bf16.safetensors \
+ --llm ../models/text_encoders/gpt-oss-20b-UD-Q8_K_XL.gguf \
+ --tokenizer ../models/tokenizers/tokenizer_gpt_oss.json \
+ --vae ../models/vae/flux2_ae.safetensors \
+ -p "A crystal dragon soaring through an aurora borealis sky, its entire body made of transparent faceted crystal refracting the green and purple aurora light into rainbow spectra, ice particles trailing from its wings, high fantasy digital art" \
+ --cfg-scale 1.0 \
+ --steps 4 \
+ -v
```
<img width="256" alt="Lens Turbo example" src="../../assets/lens/turbo_example.png" />
diff --git a/docs/models/lingbot_video.md b/docs/models/lingbot_video.md
index b92165a..a085c89 100644
--- a/docs/models/lingbot_video.md
+++ b/docs/models/lingbot_video.md
@@ -1,20 +1,73 @@
-# How to Use
+# LingBot-Video
Lingbot Video uses a Lingbot diffusion transformer, the Wan2.1 VAE, and Qwen3-VL 4B as the LLM text encoder.
-## Download weights
+## Model files
-- Download lingbot-video-dense-1.3b
- - safetensors: https://huggingface.co/robbyant/lingbot-video-dense-1.3b/tree/main/transformer
-- Download lingbot-video-moe-30b-a3b
- - safetensors: https://huggingface.co/robbyant/lingbot-video-moe-30b-a3b/tree/main/transformer
-- Download vae
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/blob/main/split_files/vae/wan_2.1_vae.safetensors
-- Download Qwen3-VL 4B
- - safetensors: https://huggingface.co/Comfy-Org/Krea-2/tree/main/text_encoders
- - gguf: https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct-GGUF/tree/main
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| lingbot-video-dense-1.3b | [Safetensors](https://huggingface.co/robbyant/lingbot-video-dense-1.3b/tree/main/transformer) | `--diffusion-model` | Choose matching variant |
+| lingbot-video-moe-30b-a3b | [Safetensors](https://huggingface.co/robbyant/lingbot-video-moe-30b-a3b/tree/main/transformer) | `--diffusion-model` | Choose matching variant |
+| vae | [Safetensors](https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/blob/main/split_files/vae/wan_2.1_vae.safetensors) | `--vae` | Use matching VAE |
+| Qwen3-VL 4B | [Safetensors](https://huggingface.co/Comfy-Org/Krea-2/tree/main/text_encoders)<br>[GGUF](https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct-GGUF/tree/main) | `--llm` | Use matching text encoder |
-## Notes
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| LingBot Video Dense 1.3B (`lingbot-video-dense`) | `diffusion_model`, `llm`, `vae`, `tae` |
+| LingBot Video MoE 30B A3B (`lingbot-video-moe`) | `diffusion_model`, `llm`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### LingBot-Video T2V
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\lingbot-video-dens-1.3b.safetensors `
+ --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ -p "{`"caption`":{`"comprehensive_description`":`"A lovely cat sits comfortably on a soft cushion near a sunlit window, looking calm, gentle, and adorable. The cat has soft fluffy fur, bright expressive eyes, small rounded ears, delicate whiskers, and a relaxed posture. Warm daylight falls across the cat from one side, creating soft highlights on the fur and a cozy glow around the scene. The background is softly blurred, showing hints of a peaceful indoor home environment with warm tones and gentle natural light. The overall atmosphere is cute, tender, serene, and photorealistic, emphasizing the cats charming appearance, soft texture, and affectionate presence.`",`"camera_info`":{`"color`":`"Warm`",`"frame_size`":`"Close Up`",`"shot_type_angle`":`"Eye level`",`"lens_size`":`"Medium Lens`",`"composition`":`"Centered balanced`",`"lighting`":`"Soft light`",`"lighting_type`":`"Daylight`"},`"world_knowledge`":[],`"prominent_elements`":[{`"name`":`"lovely cat`",`"description`":`"A cute and gentle domestic cat with soft fluffy fur, expressive eyes, and a calm relaxed presence.`",`"location`":`"center of the frame`",`"relative_size`":`"large`",`"shape_and_color`":`"Small animal body with rounded face, triangular ears, bright eyes, and soft fur in warm natural tones`",`"texture`":`"soft, fluffy, silky`",`"appearance_details`":`"The cat has clean well-groomed fur, delicate whiskers, small ears, a cute nose, and bright attentive eyes. Its expression appears calm, affectionate, and slightly curious.`",`"relationship`":`"Acts as the main subject and emotional focal point of the scene.`",`"orientation`":`"facing the camera`",`"pose`":`"sitting comfortably with a relaxed posture`",`"expression`":`"gentle, adorable, calm, slightly curious`",`"clothing`":`"`",`"gender`":`"`",`"skin_tone_and_texture`":`"`"},{`"name`":`"cat eyes`",`"description`":`"Bright expressive eyes that give the cat a sweet and affectionate appearance.`",`"location`":`"upper center of the cat face`",`"relative_size`":`"small`",`"shape_and_color`":`"Round almond-like eyes with glossy reflections`",`"texture`":`"clear, glossy, reflective`",`"appearance_details`":`"The eyes catch the soft daylight, creating small natural highlights that make the cat look vivid and alive.`",`"relationship`":`"Enhance the emotional charm and cuteness of the cat.`",`"orientation`":`"looking toward the camera`",`"pose`":`"`",`"expression`":`"soft and attentive`",`"clothing`":`"`",`"gender`":`"`",`"skin_tone_and_texture`":`"`"},{`"name`":`"soft cushion`",`"description`":`"A comfortable cushion or blanket where the cat is resting.`",`"location`":`"bottom portion of the frame`",`"relative_size`":`"medium`",`"shape_and_color`":`"Soft rounded fabric surface in light warm neutral tones`",`"texture`":`"plush, fabric, cozy`",`"appearance_details`":`"The cushion gently supports the cat and adds a comfortable home-like feeling to the scene.`",`"relationship`":`"Provides a cozy resting place for the cat.`",`"orientation`":`"horizontal`",`"pose`":`"`",`"expression`":`"`",`"clothing`":`"`",`"gender`":`"`",`"skin_tone_and_texture`":`"`"},{`"name`":`"sunlit indoor background`",`"description`":`"A softly blurred indoor background with warm daylight and peaceful home atmosphere.`",`"location`":`"behind the cat, filling the upper and side areas of the frame`",`"relative_size`":`"large`",`"shape_and_color`":`"Soft abstract shapes in warm beige, cream, and pale golden tones`",`"texture`":`"soft, blurry, bokeh-like`",`"appearance_details`":`"The background is intentionally out of focus, keeping attention on the cat while creating a cozy and serene mood.`",`"relationship`":`"Provides a warm and gentle environment that supports the cute domestic scene.`",`"orientation`":`"upright`",`"pose`":`"`",`"expression`":`"`",`"clothing`":`"`",`"gender`":`"`",`"skin_tone_and_texture`":`"`",`"is_cluster`":true,`"number_of_objects`":`"numerous`"}]}}" `
+ -n "{`"universal_negative`":{`"visual_quality`":[`"low quality`",`"worst quality`",`"blurry`",`"pixelated`",`"jpeg artifacts`",`"low resolution`",`"unstable color`",`"color flicker`",`"underexposed`",`"overexposed`",`"invisible subject`",`"subject hidden in darkness`"],`"artistic_style`":[`"painting`",`"illustration`",`"drawing`",`"cartoon`",`"3d render`",`"cgi`",`"sketch`",`"digital art`"],`"composition_and_content`":[`"text`",`"watermark`",`"signature`",`"logo`",`"subtitles`",`"pillarboxed`",`"side bars`",`"portrait image in landscape frame`"],`"temporal_and_motion_stability`":[`"flickering`",`"jittery`",`"motion blur`",`"temporal inconsistency`",`"warping`",`"morphing`",`"incoherent motion`",`"unnatural movement`",`"static object with sudden jump`",`"frame-to-frame inconsistency`"],`"material_and_structure`":[`"plastic-like glass`",`"unrealistic texture`",`"deformed bottle`",`"liquid freezing improperly`",`"distorted reflections`"]}}" `
+ --cfg-scale 3 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ -v
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/lingbot-video-dens-1.3b.safetensors \
+ --llm ../models/text_encoders/Qwen3-VL-4B-Instruct-Q4_K_M.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ -p "{\"caption\":{\"comprehensive_description\":\"A lovely cat sits comfortably on a soft cushion near a sunlit window, looking calm, gentle, and adorable. The cat has soft fluffy fur, bright expressive eyes, small rounded ears, delicate whiskers, and a relaxed posture. Warm daylight falls across the cat from one side, creating soft highlights on the fur and a cozy glow around the scene. The background is softly blurred, showing hints of a peaceful indoor home environment with warm tones and gentle natural light. The overall atmosphere is cute, tender, serene, and photorealistic, emphasizing the cats charming appearance, soft texture, and affectionate presence.\",\"camera_info\":{\"color\":\"Warm\",\"frame_size\":\"Close Up\",\"shot_type_angle\":\"Eye level\",\"lens_size\":\"Medium Lens\",\"composition\":\"Centered balanced\",\"lighting\":\"Soft light\",\"lighting_type\":\"Daylight\"},\"world_knowledge\":[],\"prominent_elements\":[{\"name\":\"lovely cat\",\"description\":\"A cute and gentle domestic cat with soft fluffy fur, expressive eyes, and a calm relaxed presence.\",\"location\":\"center of the frame\",\"relative_size\":\"large\",\"shape_and_color\":\"Small animal body with rounded face, triangular ears, bright eyes, and soft fur in warm natural tones\",\"texture\":\"soft, fluffy, silky\",\"appearance_details\":\"The cat has clean well-groomed fur, delicate whiskers, small ears, a cute nose, and bright attentive eyes. Its expression appears calm, affectionate, and slightly curious.\",\"relationship\":\"Acts as the main subject and emotional focal point of the scene.\",\"orientation\":\"facing the camera\",\"pose\":\"sitting comfortably with a relaxed posture\",\"expression\":\"gentle, adorable, calm, slightly curious\",\"clothing\":\"\",\"gender\":\"\",\"skin_tone_and_texture\":\"\"},{\"name\":\"cat eyes\",\"description\":\"Bright expressive eyes that give the cat a sweet and affectionate appearance.\",\"location\":\"upper center of the cat face\",\"relative_size\":\"small\",\"shape_and_color\":\"Round almond-like eyes with glossy reflections\",\"texture\":\"clear, glossy, reflective\",\"appearance_details\":\"The eyes catch the soft daylight, creating small natural highlights that make the cat look vivid and alive.\",\"relationship\":\"Enhance the emotional charm and cuteness of the cat.\",\"orientation\":\"looking toward the camera\",\"pose\":\"\",\"expression\":\"soft and attentive\",\"clothing\":\"\",\"gender\":\"\",\"skin_tone_and_texture\":\"\"},{\"name\":\"soft cushion\",\"description\":\"A comfortable cushion or blanket where the cat is resting.\",\"location\":\"bottom portion of the frame\",\"relative_size\":\"medium\",\"shape_and_color\":\"Soft rounded fabric surface in light warm neutral tones\",\"texture\":\"plush, fabric, cozy\",\"appearance_details\":\"The cushion gently supports the cat and adds a comfortable home-like feeling to the scene.\",\"relationship\":\"Provides a cozy resting place for the cat.\",\"orientation\":\"horizontal\",\"pose\":\"\",\"expression\":\"\",\"clothing\":\"\",\"gender\":\"\",\"skin_tone_and_texture\":\"\"},{\"name\":\"sunlit indoor background\",\"description\":\"A softly blurred indoor background with warm daylight and peaceful home atmosphere.\",\"location\":\"behind the cat, filling the upper and side areas of the frame\",\"relative_size\":\"large\",\"shape_and_color\":\"Soft abstract shapes in warm beige, cream, and pale golden tones\",\"texture\":\"soft, blurry, bokeh-like\",\"appearance_details\":\"The background is intentionally out of focus, keeping attention on the cat while creating a cozy and serene mood.\",\"relationship\":\"Provides a warm and gentle environment that supports the cute domestic scene.\",\"orientation\":\"upright\",\"pose\":\"\",\"expression\":\"\",\"clothing\":\"\",\"gender\":\"\",\"skin_tone_and_texture\":\"\",\"is_cluster\":true,\"number_of_objects\":\"numerous\"}]}}" \
+ -n "{\"universal_negative\":{\"visual_quality\":[\"low quality\",\"worst quality\",\"blurry\",\"pixelated\",\"jpeg artifacts\",\"low resolution\",\"unstable color\",\"color flicker\",\"underexposed\",\"overexposed\",\"invisible subject\",\"subject hidden in darkness\"],\"artistic_style\":[\"painting\",\"illustration\",\"drawing\",\"cartoon\",\"3d render\",\"cgi\",\"sketch\",\"digital art\"],\"composition_and_content\":[\"text\",\"watermark\",\"signature\",\"logo\",\"subtitles\",\"pillarboxed\",\"side bars\",\"portrait image in landscape frame\"],\"temporal_and_motion_stability\":[\"flickering\",\"jittery\",\"motion blur\",\"temporal inconsistency\",\"warping\",\"morphing\",\"incoherent motion\",\"unnatural movement\",\"static object with sudden jump\",\"frame-to-frame inconsistency\"],\"material_and_structure\":[\"plastic-like glass\",\"unrealistic texture\",\"deformed bottle\",\"liquid freezing improperly\",\"distorted reflections\"]}}" \
+ --cfg-scale 3 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ -v
+```
+
+## Notes and limitations
- Use `-M vid_gen`.
- T2V uses the text prompt only.
@@ -22,11 +75,3 @@ Lingbot Video uses a Lingbot diffusion transformer, the Wan2.1 VAE, and Qwen3-VL
Qwen3-VL prompt enhancer when vision weights are available.
- Video frames are aligned to Wan-style temporal compression, so use frame counts
like 33, 49, or 81.
-
-## Examples
-
-### LingBot-Video T2V
-
-```sh
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\lingbot-video-dens-1.3b.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --vae ..\models\vae\wan_2.1_vae.safetensors -p '{"caption":{"comprehensive_description":"A lovely cat sits comfortably on a soft cushion near a sunlit window, looking calm, gentle, and adorable. The cat has soft fluffy fur, bright expressive eyes, small rounded ears, delicate whiskers, and a relaxed posture. Warm daylight falls across the cat from one side, creating soft highlights on the fur and a cozy glow around the scene. The background is softly blurred, showing hints of a peaceful indoor home environment with warm tones and gentle natural light. The overall atmosphere is cute, tender, serene, and photorealistic, emphasizing the cat''s charming appearance, soft texture, and affectionate presence.","camera_info":{"color":"Warm","frame_size":"Close Up","shot_type_angle":"Eye level","lens_size":"Medium Lens","composition":"Centered balanced","lighting":"Soft light","lighting_type":"Daylight"},"world_knowledge":[],"prominent_elements":[{"name":"lovely cat","description":"A cute and gentle domestic cat with soft fluffy fur, expressive eyes, and a calm relaxed presence.","location":"center of the frame","relative_size":"large","shape_and_color":"Small animal body with rounded face, triangular ears, bright eyes, and soft fur in warm natural tones","texture":"soft, fluffy, silky","appearance_details":"The cat has clean well-groomed fur, delicate whiskers, small ears, a cute nose, and bright attentive eyes. Its expression appears calm, affectionate, and slightly curious.","relationship":"Acts as the main subject and emotional focal point of the scene.","orientation":"facing the camera","pose":"sitting comfortably with a relaxed posture","expression":"gentle, adorable, calm, slightly curious","clothing":"","gender":"","skin_tone_and_texture":""},{"name":"cat eyes","description":"Bright expressive eyes that give the cat a sweet and affectionate appearance.","location":"upper center of the cat face","relative_size":"small","shape_and_color":"Round almond-like eyes with glossy reflections","texture":"clear, glossy, reflective","appearance_details":"The eyes catch the soft daylight, creating small natural highlights that make the cat look vivid and alive.","relationship":"Enhance the emotional charm and cuteness of the cat.","orientation":"looking toward the camera","pose":"","expression":"soft and attentive","clothing":"","gender":"","skin_tone_and_texture":""},{"name":"soft cushion","description":"A comfortable cushion or blanket where the cat is resting.","location":"bottom portion of the frame","relative_size":"medium","shape_and_color":"Soft rounded fabric surface in light warm neutral tones","texture":"plush, fabric, cozy","appearance_details":"The cushion gently supports the cat and adds a comfortable home-like feeling to the scene.","relationship":"Provides a cozy resting place for the cat.","orientation":"horizontal","pose":"","expression":"","clothing":"","gender":"","skin_tone_and_texture":""},{"name":"sunlit indoor background","description":"A softly blurred indoor background with warm daylight and peaceful home atmosphere.","location":"behind the cat, filling the upper and side areas of the frame","relative_size":"large","shape_and_color":"Soft abstract shapes in warm beige, cream, and pale golden tones","texture":"soft, blurry, bokeh-like","appearance_details":"The background is intentionally out of focus, keeping attention on the cat while creating a cozy and serene mood.","relationship":"Provides a warm and gentle environment that supports the cute domestic scene.","orientation":"upright","pose":"","expression":"","clothing":"","gender":"","skin_tone_and_texture":"","is_cluster":true,"number_of_objects":"numerous"}]}}' -n '{"universal_negative":{"visual_quality":["low quality","worst quality","blurry","pixelated","jpeg artifacts","low resolution","unstable color","color flicker","underexposed","overexposed","invisible subject","subject hidden in darkness"],"artistic_style":["painting","illustration","drawing","cartoon","3d render","cgi","sketch","digital art"],"composition_and_content":["text","watermark","signature","logo","subtitles","pillarboxed","side bars","portrait image in landscape frame"],"temporal_and_motion_stability":["flickering","jittery","motion blur","temporal inconsistency","warping","morphing","incoherent motion","unnatural movement","static object with sudden jump","frame-to-frame inconsistency"],"material_and_structure":["plastic-like glass","unrealistic texture","deformed bottle","liquid freezing improperly","distorted reflections"]}}' --offload-to-cpu --cfg-scale 3 --video-frames 33 -v
-```
diff --git a/docs/models/llada_image.md b/docs/models/llada_image.md
index 94cb5c8..d627b7b 100644
--- a/docs/models/llada_image.md
+++ b/docs/models/llada_image.md
@@ -1,11 +1,19 @@
-# How to Use
+# LLaDA-Image
-LLaDA-Image is a 6B text-to-image and instruction-guided editing model. The denoiser is a
-Lumina2/Z-Image-style NextDiT conditioned by a LLaDA2-MoE diffusion-LLM text encoder, and it
-reuses the Flux.2 VAE. Two checkpoints are published: a 50-step base model and
-LLaDA-Image-Turbo, a 4-step distilled model.
+LLaDA-Image is a 6B text-to-image and instruction-guided editing model using a
+LLaDA2 text encoder and the FLUX.2 VAE. Choose the 50-step Base checkpoint or the
+4-step Turbo checkpoint, keeping each variant's text encoder and connectors
+together.
-## Download weights
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Transformer | Choose the matching Base or Turbo weights below | `--diffusion-model` | Required |
+| Text encoder | Use the text encoder from the same Base or Turbo checkpoint | `--llm` | Required; variants are not interchangeable |
+| Tokenizer | `tokenizer/tokenizer.json` from either original repository below | `--tokenizer` | Required; shared by Base and Turbo |
+| FLUX.2 VAE | `llada_vae.safetensors`, downloaded from either original repository below | `--vae` | Required; shared by Base and Turbo |
+| Connectors | Matching `*-connectors.safetensors` or `*-connectors-edit.safetensors` below | `--embeddings-connectors` | Editing requires the file including SigVQ |
Four components are required: a transformer, a text encoder, a VAE, and a connectors file
holding the QueryFormer, the text projection and, for editing, the SigVQ image encoder.
@@ -52,19 +60,47 @@ Other quantizations of the transformer and the text encoder are in the same repo
The VAE comes from the original repository,
https://huggingface.co/inclusionAI/LLaDA-Image, and is the same file as the Turbo one.
-### Converting the weights yourself
+### Optional conversion
+
+Run executable conversion examples from the build directory using the
+[shared path and shell conventions](README.md#example-conventions).
+
+#### Converting the weights yourself
The transformer has to go in through `--diffusion-model` so that its tensor names keep the
prefix the loader expects, while the text encoder goes in through `-m`:
-```bash
-./bin/sd-cli -M convert --diffusion-model transformer/diffusion_pytorch_model.safetensors.index.json \
- -o llada-image-f16.gguf --type f16
-./bin/sd-cli -M convert -m text_encoder/model.safetensors.index.json \
- -o llada-image-text_encoder-q8_0.gguf --type q8_0
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M convert `
+ --diffusion-model ..\models\transformer\diffusion_pytorch_model.safetensors.index.json `
+ --type f16 `
+ -o llada-image-f16.gguf
+.\bin\Release\sd-cli.exe `
+ -M convert `
+ -m ..\models\text_encoder\model.safetensors.index.json `
+ --type q8_0 `
+ -o llada-image-text_encoder-q8_0.gguf
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M convert \
+ --diffusion-model ../models/transformer/diffusion_pytorch_model.safetensors.index.json \
+ --type f16 \
+ -o llada-image-f16.gguf
+./bin/sd-cli \
+ -M convert \
+ -m ../models/text_encoder/model.safetensors.index.json \
+ --type q8_0 \
+ -o llada-image-text_encoder-q8_0.gguf
```
-### Building the connector file yourself
+#### Building the connector file yourself
`--embeddings-connectors` takes one file, so the QueryFormer, the text projection and
(for editing) the SigVQ encoder have to be combined into a single Safetensors file, each
@@ -85,43 +121,103 @@ for prefix, path in [
save_file(merged, "llada_connectors.safetensors")
```
-## Examples
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| LLaDA Image Turbo (`llada-image-turbo`) | `diffusion_model`, `llm`, `tokenizer`, `embeddings_connectors`, `vae`, `tae` |
+| LLaDA Image (base) (`llada-image`) | `diffusion_model`, `llm`, `tokenizer`, `embeddings_connectors`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Text to image
-### Text to image
+**Windows (PowerShell)**
-```bash
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\llada-image-turbo-f16.gguf `
+ --llm ..\models\text_encoders\llada-image-turbo-text_encoder-q8_0.gguf `
+ --tokenizer ..\models\tokenizers\tokenizer.json `
+ --vae ..\models\vae\llada_vae.safetensors `
+ --embeddings-connectors ..\models\text_encoders\llada-image-turbo-connectors.safetensors `
+ --prompt "a lovely cat holding a sign says 'llada.cpp'" `
+ --steps 4 `
+ --cfg-scale 1.0 `
+ --width 1024 `
+ --height 1024 `
+ --seed 42 `
+ --output output.png
+```
+
+**Linux/macOS**
+
+```sh
./bin/sd-cli \
- --diffusion-model /path/to/llada-image-turbo-f16.gguf \
- --llm /path/to/llada-image-turbo-text_encoder-q8_0.gguf \
- --tokenizer /path/to/tokenizer.json \
- --vae /path/to/llada_vae.safetensors \
- --embeddings-connectors /path/to/llada-image-turbo-connectors.safetensors \
+ --diffusion-model ../models/diffusion_models/llada-image-turbo-f16.gguf \
+ --llm ../models/text_encoders/llada-image-turbo-text_encoder-q8_0.gguf \
+ --tokenizer ../models/tokenizers/tokenizer.json \
+ --vae ../models/vae/llada_vae.safetensors \
+ --embeddings-connectors ../models/text_encoders/llada-image-turbo-connectors.safetensors \
--prompt "a lovely cat holding a sign says 'llada.cpp'" \
- --width 1024 \
- --height 1024 \
--steps 4 \
--cfg-scale 1.0 \
+ --width 1024 \
+ --height 1024 \
--seed 42 \
--output output.png
```
<img width="256" alt="LLaDA-Image example" src="../../assets/llada_image/example.png" />
-### Image editing
+#### Image editing
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\llada-image-turbo-f16.gguf `
+ --llm ..\models\text_encoders\llada-image-turbo-text_encoder-q8_0.gguf `
+ --tokenizer ..\models\tokenizers\tokenizer.json `
+ --vae ..\models\vae\llada_vae.safetensors `
+ --embeddings-connectors ..\models\text_encoders\llada-image-turbo-connectors-edit.safetensors `
+ --ref-image ..\inputs\input.png `
+ --prompt "change the sign text to 'sd.cpp'" `
+ --steps 4 `
+ --cfg-scale 1.0 `
+ --width 1024 `
+ --height 1024 `
+ --output output.png
+```
-```bash
+**Linux/macOS**
+
+```sh
./bin/sd-cli \
- --diffusion-model /path/to/llada-image-turbo-f16.gguf \
- --llm /path/to/llada-image-turbo-text_encoder-q8_0.gguf \
- --tokenizer /path/to/tokenizer.json \
- --vae /path/to/llada_vae.safetensors \
- --embeddings-connectors /path/to/llada-image-turbo-connectors-edit.safetensors \
- --ref-image /path/to/input.png \
+ --diffusion-model ../models/diffusion_models/llada-image-turbo-f16.gguf \
+ --llm ../models/text_encoders/llada-image-turbo-text_encoder-q8_0.gguf \
+ --tokenizer ../models/tokenizers/tokenizer.json \
+ --vae ../models/vae/llada_vae.safetensors \
+ --embeddings-connectors ../models/text_encoders/llada-image-turbo-connectors-edit.safetensors \
+ --ref-image ../inputs/input.png \
--prompt "change the sign text to 'sd.cpp'" \
- --width 1024 \
- --height 1024 \
--steps 4 \
--cfg-scale 1.0 \
+ --width 1024 \
+ --height 1024 \
--output output.png
```
@@ -133,7 +229,7 @@ before VAE encoding. SigVQ uses bilinear resizing to half the output resolution
normalized to `[-1, 1]`. CFG keeps the source latent in both branches and uses SigVQ features
only in the positive branch. Editing requires connectors that include the SigVQ weights.
-## Notes
+## Notes and limitations
- Use 4 steps and `--cfg-scale 1.0` for LLaDA-Image-Turbo; the guidance is distilled away, so
a higher CFG degrades output and doubles the text encoder cost. The 50-step base model uses
diff --git a/docs/models/longcat_image.md b/docs/models/longcat_image.md
index fa70c08..ec2fae1 100644
--- a/docs/models/longcat_image.md
+++ b/docs/models/longcat_image.md
@@ -1,30 +1,70 @@
-# How to Use
+# LongCat Image
LongCat-Image uses a LongCat diffusion transformer, the FLUX VAE, and Qwen2.5-VL as the LLM text encoder.
-## Download weights
+## Model files
-- Download LongCat Image
- - safetensors: https://huggingface.co/Comfy-Org/LongCat-Image/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/vantagewithai/LongCat-Image-GGUF/tree/main/comfy
-- Download LongCat Image Edit
- - LongCat Image Edit Turbo: https://huggingface.co/meituan-longcat/LongCat-Image-Edit-Turbo
- - gguf: https://huggingface.co/vantagewithai/LongCat-Image-Edit-GGUF/tree/main
-- Download vae
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.1-dev/blob/main/ae.safetensors
-- Download qwen_2.5_vl 7b
- - safetensors: https://huggingface.co/Comfy-Org/Qwen-Image_ComfyUI/tree/main/split_files/text_encoders
- - gguf: https://huggingface.co/mradermacher/Qwen2.5-VL-7B-Instruct-GGUF/tree/main
- - For image editing with GGUF text encoders, also download the matching mmproj file and pass it with `--llm_vision`.
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| LongCat Image | [Safetensors](https://huggingface.co/Comfy-Org/LongCat-Image/tree/main/split_files/diffusion_models)<br>[GGUF](https://huggingface.co/vantagewithai/LongCat-Image-GGUF/tree/main/comfy) | `--diffusion-model` | Choose matching variant |
+| LongCat Image Edit | LongCat Image Edit Turbo: [Download](https://huggingface.co/meituan-longcat/LongCat-Image-Edit-Turbo)<br>[GGUF](https://huggingface.co/vantagewithai/LongCat-Image-Edit-GGUF/tree/main) | `--diffusion-model` | Choose matching variant |
+| vae | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.1-dev/blob/main/ae.safetensors) | `--vae` | Use matching VAE |
+| qwen_2.5_vl 7b | [Safetensors](https://huggingface.co/Comfy-Org/Qwen-Image_ComfyUI/tree/main/split_files/text_encoders)<br>[GGUF](https://huggingface.co/mradermacher/Qwen2.5-VL-7B-Instruct-GGUF/tree/main)<br>For image editing with GGUF text encoders, also download the matching mmproj file and pass it with `--llm_vision`. | `--llm` | Use matching text encoder |
-## Run
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| LongCat Image (`longcat-image`) | `diffusion_model`, `llm`, `vae`, `tae` |
+| LongCat Image Edit (`longcat-image-edit`) | `diffusion_model`, `llm`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
LongCat uses quoted text for character-level text rendering. Put target text inside single quotes, double quotes, or Chinese quotes.
-### LongCat Image
+#### LongCat Image
+
+**Windows (PowerShell)**
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\LongCat-Image-Q4_K_M.gguf `
+ --vae ..\models\vae\ae.sft `
+ --llm ..\models\text_encoders\Qwen2.5-VL-7B-Instruct-Q8_0.gguf `
+ -p "a lovely cat holding a sign says 'longcat.cpp'" `
+ --cfg-scale 5.0 `
+ --sampling-method euler `
+ --flow-shift 3 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\LongCat-Image-Q4_K_M.gguf --vae ..\models\vae\ae.sft --llm ..\models\text_encoders\Qwen2.5-VL-7B-Instruct-Q8_0.gguf -p "a lovely cat holding a sign says 'longcat.cpp'" --cfg-scale 5.0 --sampling-method euler --flow-shift 3 -v --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/LongCat-Image-Q4_K_M.gguf \
+ --vae ../models/vae/ae.sft \
+ --llm ../models/text_encoders/Qwen2.5-VL-7B-Instruct-Q8_0.gguf \
+ -p "a lovely cat holding a sign says 'longcat.cpp'" \
+ --cfg-scale 5.0 \
+ --sampling-method euler \
+ --flow-shift 3 \
+ --offload-to-cpu \
+ -v
```
<img alt="longcat example" src="../../assets/longcat/example.png" />
diff --git a/docs/models/lora.md b/docs/models/lora.md
index d6dc718..56cb60b 100644
--- a/docs/models/lora.md
+++ b/docs/models/lora.md
@@ -1,18 +1,50 @@
-## LoRA
+# LoRA
-- You can specify the directory where the lora weights are stored via `--lora-model-dir`. If not specified, the default is the current working directory.
+LoRA weights adapt a compatible base model. Select a LoRA by name and strength
+using `<lora:NAME:STRENGTH>` in the prompt.
-- LoRA is specified via prompt, just like [stable-diffusion-webui](https://github.com/AUTOMATIC1111/stable-diffusion-webui/wiki/Features#lora).
+## Model files
-Here's a simple example:
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Base model | [Compatible model checkpoint](README.md) | `-m` / model component options | Required |
+| LoRA weights | `marblesh.safetensors` or `marblesh.ckpt` for the example | `--lora-model-dir` and `<lora:NAME:STRENGTH>` in the prompt | Match the base model family |
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Load a compatible base model with its recipe, then select the LoRA for generation.
+See [Web UI guide](../../examples/server/README.md#web-ui) for the shared workflow.
+
+### CLI
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\v1-5-pruned-emaonly.safetensors `
+ --lora-model-dir ..\models\loras `
+ -p "a lovely cat<lora:marblesh:1>"
```
-./bin/sd-cli -m ../models/v1-5-pruned-emaonly.safetensors -p "a lovely cat<lora:marblesh:1>" --lora-model-dir ../models
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -m ../models/checkpoints/v1-5-pruned-emaonly.safetensors \
+ --lora-model-dir ../models/loras \
+ -p "a lovely cat<lora:marblesh:1>"
```
-`../models/marblesh.safetensors` or `../models/marblesh.ckpt` will be applied to the model
+The example loads `../models/loras/marblesh.safetensors` or
+`../models/loras/marblesh.ckpt` (use backslashes on Windows).
-# Lora Apply Mode
+## Options
+
+### LoRA apply mode
There are two ways to apply LoRA: **immediately** and **at_runtime**. You can specify it using the `--lora-apply-mode` parameter.
@@ -24,3 +56,7 @@ By default, the mode is selected automatically:
The **immediately** mode may have precision and compatibility issues with quantized parameters, but it usually offers faster inference speed and, in some cases, lower memory usage.
In contrast, the **at_runtime** mode provides better compatibility and higher precision, but inference may be slower and memory usage may be higher in some cases.
+## Notes and limitations
+
+Choose LoRA weights trained for the base model. See the
+[WebUI-style LoRA syntax](https://github.com/AUTOMATIC1111/stable-diffusion-webui/wiki/Features#lora).
diff --git a/docs/models/ltx2.md b/docs/models/ltx2.md
index 10cd8ad..1785487 100644
--- a/docs/models/ltx2.md
+++ b/docs/models/ltx2.md
@@ -1,61 +1,130 @@
-# How to Use
+# LTX-2
-Both LTX-2.3 and LTX-2.5 are supported. The two share a transformer, video VAE and audio
-VAE architecture; LTX-2.5 drops the video FFN biases, adds a learned keyframe
-absolute-position embedding, and pairs with a Gemma 4 text encoder instead of Gemma 3.
-Everything is detected from the weights, so the command lines differ only in which files
-you pass.
+LTX-2.3 and LTX-2.5 support text-to-video and image-to-video generation.
+LTX-2.3 uses Gemma 3 with separate embedding connectors. LTX-2.5 requires its
+LTX-specific Gemma 4 encoder with the text projection included and the conv video VAE.
-# LTX-2.3
-
-## Download weights
+## Model files
### LTX-2.3
-- Download LTX-2.3
- - safetensors: https://huggingface.co/Kijai/LTX2.3_comfy/tree/main/diffusion_models
- - gguf: https://huggingface.co/unsloth/LTX-2.3-GGUF/tree/main
-- Download gemma-3-12b-it
- - gguf: https://huggingface.co/unsloth/gemma-3-12b-it-GGUF/tree/main
-- Download embeddings connectors
- - safetensors: https://huggingface.co/unsloth/LTX-2.3-GGUF/tree/main/text_encoders
-- Download vae
- - safetensors: https://huggingface.co/unsloth/LTX-2.3-GGUF/tree/main/vae
-- Download audio vae
- - safetensors: https://huggingface.co/unsloth/LTX-2.3-GGUF/tree/main/vae
-- Download LTX spatial latent upscaler
- - safetensors: https://huggingface.co/Lightricks/LTX-2.3/resolve/main/ltx-2.3-spatial-upscaler-x2-1.1.safetensors
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| LTX-2.3 transformer | [Safetensors](https://huggingface.co/Kijai/LTX2.3_comfy/tree/main/diffusion_models)<br>[GGUF](https://huggingface.co/unsloth/LTX-2.3-GGUF/tree/main) | `--diffusion-model` | Required |
+| Gemma 3 12B text encoder | [GGUF](https://huggingface.co/unsloth/gemma-3-12b-it-GGUF/tree/main) | `--llm` | Required for 2.3 |
+| LTX-2.3 connectors | [Safetensors](https://huggingface.co/unsloth/LTX-2.3-GGUF/tree/main/text_encoders) | `--embeddings-connectors` | Required for 2.3 |
+| LTX-2.3 video VAE | [Safetensors](https://huggingface.co/unsloth/LTX-2.3-GGUF/tree/main/vae) | `--vae` | Required for these examples |
+| LTX-2.3 audio VAE | [Safetensors](https://huggingface.co/unsloth/LTX-2.3-GGUF/tree/main/vae) | `--audio-vae` | For audio output |
+| LTX-2.3 spatial upscaler | [Safetensors](https://huggingface.co/Lightricks/LTX-2.3/resolve/main/ltx-2.3-spatial-upscaler-x2-1.1.safetensors) | `--hires-upscalers-dir` | For latent spatial upscaling |
### LTX-2.5
-- Download LTX-2.5
- - safetensors: https://huggingface.co/Lightricks/LTX-2.5/tree/main/diffusion_models
- - gguf: https://huggingface.co/vantagewithai/LTX-2.5-GGUF/tree/main
-- Download the text encoder. This is a Gemma 4 12B fine-tuned for LTX with the text
- projection bundled in, so no separate `--embeddings-connectors` file is needed. Google's
- stock Gemma 4 is not a substitute.
- - safetensors: https://huggingface.co/Lightricks/LTX-2.5/blob/main/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors
-- Download the video vae. Use the **conv** variant: `ltx-2.5-video-vae-conv-bf16.safetensors`.
- The default `ltx-2.5-video-vae-bf16.safetensors` is a diffusion decoder, which is not
- implemented here.
- - safetensors: https://huggingface.co/Lightricks/LTX-2.5/blob/main/vae/ltx-2.5-video-vae-conv-bf16.safetensors
-- Download the audio vae
- - safetensors: https://huggingface.co/Lightricks/LTX-2.5/blob/main/vae/ltx-2.5-audio-vae-bf16.safetensors
-- Download the LTX spatial latent upscaler
- - safetensors: https://huggingface.co/Lightricks/LTX-2.5/blob/main/latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| LTX-2.5 transformer | [Safetensors](https://huggingface.co/Lightricks/LTX-2.5/tree/main/diffusion_models)<br>[GGUF](https://huggingface.co/vantagewithai/LTX-2.5-GGUF/tree/main) | `--diffusion-model` | Required |
+| LTX Gemma 4 12B with projection | projection bundled in, so no separate `--embeddings-connectors` file is needed. Google's<br>stock Gemma 4 is not a substitute.<br>[Safetensors](https://huggingface.co/Lightricks/LTX-2.5/blob/main/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors) | `--llm` | Required; stock Gemma 4 is incompatible |
+| LTX-2.5 conv video VAE | The default `ltx-2.5-video-vae-bf16.safetensors` is a diffusion decoder, which is not<br>implemented here.<br>[Safetensors](https://huggingface.co/Lightricks/LTX-2.5/blob/main/vae/ltx-2.5-video-vae-conv-bf16.safetensors) | `--vae` | Use the conv variant |
+| LTX-2.5 audio VAE | [Safetensors](https://huggingface.co/Lightricks/LTX-2.5/blob/main/vae/ltx-2.5-audio-vae-bf16.safetensors) | `--audio-vae` | For audio output |
+| LTX-2.5 spatial upscaler | [Safetensors](https://huggingface.co/Lightricks/LTX-2.5/blob/main/latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors) | `--hires-upscalers-dir` | For latent spatial upscaling |
+
+### Optional conversion
+
+Run executable conversion examples from the build directory using the
+[shared path and shell conventions](README.md#example-conventions).
+
+#### Quantize the LTX-2.5 text encoder
To run the text encoder quantized, convert it once with sd-cli:
-```
-.\bin\Release\sd-cli.exe -M convert -m ..\models\text_encoders\gemma4-12b-with-proj-ltx-2.5-bf16.safetensors --type q8_0 -o ..\models\text_encoders\gemma4-12b-with-proj-ltx-2.5-Q8_0.gguf
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M convert `
+ -m ..\models\text_encoders\gemma4-12b-with-proj-ltx-2.5-bf16.safetensors `
+ --type q8_0 `
+ -o ..\models\text_encoders\gemma4-12b-with-proj-ltx-2.5-Q8_0.gguf
```
-## Examples
+**Linux/macOS**
-### LTX-2.3 dev T2V
+```sh
+./bin/sd-cli \
+ -M convert \
+ -m ../models/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \
+ --type q8_0 \
+ -o ../models/text_encoders/gemma4-12b-with-proj-ltx-2.5-Q8_0.gguf
+```
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| LTX 2.3 dev (`ltx23-dev`) | `diffusion_model`, `llm`, `embeddings_connectors`, `vae`, `tae`, `audio_vae` |
+| LTX 2.3 Distilled 1.1 (`ltx23-distilled`) | `diffusion_model`, `llm`, `embeddings_connectors`, `vae`, `tae`, `audio_vae` |
+| LTX 2.5 dev (`ltx25-dev`) | `diffusion_model`, `llm`, `vae`, `tae`, `audio_vae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### LTX-2.3 dev T2V
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\ltx-2.3-22b-dev-UD-Q4_K_M.gguf `
+ --vae ..\models\vae\ltx-2.3-22b-dev_video_vae.safetensors `
+ --audio-vae ..\models\vae\ltx-2.3-22b-dev_audio_vae.safetensors `
+ --llm ..\models\text_encoders\gemma-3-12b-it-qat-UD-Q4_K_XL.gguf `
+ --embeddings-connectors ..\models\text_encoders\ltx-2.3-22b-dev_embeddings_connectors.safetensors `
+ -p "a lovely cat" `
+ -n "worst quality, low quality, blurry, distorted, artifacts" `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ -W 1280 `
+ -H 720 `
+ --video-frames 33 `
+ --fps 24 `
+ --offload-to-cpu `
+ -v `
+ -o t2v.webm
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\ltx-2.3-22b-dev-UD-Q4_K_M.gguf --vae ..\models\vae\ltx-2.3-22b-dev_video_vae.safetensors --audio-vae ..\models\vae\ltx-2.3-22b-dev_audio_vae.safetensors --llm ..\models\text_encoders\gemma-3-12b-it-qat-UD-Q4_K_XL.gguf --embeddings-connectors ..\models\text_encoders\ltx-2.3-22b-dev_embeddings_connectors.safetensors -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "worst quality, low quality, blurry, distorted, artifacts" -W 1280 -H 720 --offload-to-cpu --video-frames 33 --fps 24 -o t2v.webm
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/ltx-2.3-22b-dev-UD-Q4_K_M.gguf \
+ --vae ../models/vae/ltx-2.3-22b-dev_video_vae.safetensors \
+ --audio-vae ../models/vae/ltx-2.3-22b-dev_audio_vae.safetensors \
+ --llm ../models/text_encoders/gemma-3-12b-it-qat-UD-Q4_K_XL.gguf \
+ --embeddings-connectors ../models/text_encoders/ltx-2.3-22b-dev_embeddings_connectors.safetensors \
+ -p "a lovely cat" \
+ -n "worst quality, low quality, blurry, distorted, artifacts" \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ -W 1280 \
+ -H 720 \
+ --video-frames 33 \
+ --fps 24 \
+ --offload-to-cpu \
+ -v \
+ -o t2v.webm
```
<video
@@ -64,10 +133,50 @@ To run the text encoder quantized, convert it once with sd-cli:
muted
style="max-width: 100%; height: auto;"></video>
-### LTX-2.3 dev I2V
-
+#### LTX-2.3 dev I2V
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\ltx-2.3-22b-dev-UD-Q4_K_M.gguf `
+ --vae ..\models\vae\ltx-2.3-22b-dev_video_vae.safetensors `
+ --audio-vae ..\models\vae\ltx-2.3-22b-dev_audio_vae.safetensors `
+ --llm ..\models\text_encoders\gemma-3-12b-it-qat-UD-Q4_K_XL.gguf `
+ --embeddings-connectors ..\models\text_encoders\ltx-2.3-22b-dev_embeddings_connectors.safetensors `
+ -p "a lovely cat" `
+ -i ..\inputs\ernie_image\turbo_example.png `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ -W 1280 `
+ -H 720 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ -v `
+ -o i2v.webm
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\ltx-2.3-22b-dev-UD-Q4_K_M.gguf --vae ..\models\vae\ltx-2.3-22b-dev_video_vae.safetensors --audio-vae ..\models\vae\ltx-2.3-22b-dev_audio_vae.safetensors --llm ..\models\text_encoders\gemma-3-12b-it-qat-UD-Q4_K_XL.gguf --embeddings-connectors ..\models\text_encoders\ltx-2.3-22b-dev_embeddings_connectors.safetensors -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -W 1280 -H 720 --offload-to-cpu --video-frames 33 -i ..\assets\ernie_image\turbo_example.png -o i2v.webm
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/ltx-2.3-22b-dev-UD-Q4_K_M.gguf \
+ --vae ../models/vae/ltx-2.3-22b-dev_video_vae.safetensors \
+ --audio-vae ../models/vae/ltx-2.3-22b-dev_audio_vae.safetensors \
+ --llm ../models/text_encoders/gemma-3-12b-it-qat-UD-Q4_K_XL.gguf \
+ --embeddings-connectors ../models/text_encoders/ltx-2.3-22b-dev_embeddings_connectors.safetensors \
+ -p "a lovely cat" \
+ -i ../inputs/ernie_image/turbo_example.png \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ -W 1280 \
+ -H 720 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ -v \
+ -o i2v.webm
```
<video
@@ -76,10 +185,52 @@ To run the text encoder quantized, convert it once with sd-cli:
muted
style="max-width: 100%; height: auto;"></video>
-### LTX-2.3 dev FLF2V
-
+#### LTX-2.3 dev FLF2V
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\ltx-2.3-22b-dev-UD-Q4_K_M.gguf `
+ --vae ..\models\vae\ltx-2.3-22b-dev_video_vae.safetensors `
+ --audio-vae ..\models\vae\ltx-2.3-22b-dev_audio_vae.safetensors `
+ --llm ..\models\text_encoders\gemma-3-12b-it-qat-UD-Q4_K_XL.gguf `
+ --embeddings-connectors ..\models\text_encoders\ltx-2.3-22b-dev_embeddings_connectors.safetensors `
+ -p "glass flower blossom" `
+ --init-img ..\inputs\start_image.png `
+ --end-img ..\inputs\end_image.png `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ -W 1280 `
+ -H 720 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ -v `
+ -o flf2v.webm
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\ltx-2.3-22b-dev-UD-Q4_K_M.gguf --vae ..\models\vae\ltx-2.3-22b-dev_video_vae.safetensors --audio-vae ..\models\vae\ltx-2.3-22b-dev_audio_vae.safetensors --llm ..\models\text_encoders\gemma-3-12b-it-qat-UD-Q4_K_XL.gguf --embeddings-connectors ..\models\text_encoders\ltx-2.3-22b-dev_embeddings_connectors.safetensors -p "glass flower blossom" --cfg-scale 6.0 --sampling-method euler -v -W 1280 -H 720 --offload-to-cpu --video-frames 33 --init-img ..\..\ComfyUI\input\start_image.png --end-img ..\..\ComfyUI\input\end_image.png -o flf2v.webm
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/ltx-2.3-22b-dev-UD-Q4_K_M.gguf \
+ --vae ../models/vae/ltx-2.3-22b-dev_video_vae.safetensors \
+ --audio-vae ../models/vae/ltx-2.3-22b-dev_audio_vae.safetensors \
+ --llm ../models/text_encoders/gemma-3-12b-it-qat-UD-Q4_K_XL.gguf \
+ --embeddings-connectors ../models/text_encoders/ltx-2.3-22b-dev_embeddings_connectors.safetensors \
+ -p "glass flower blossom" \
+ --init-img ../inputs/start_image.png \
+ --end-img ../inputs/end_image.png \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ -W 1280 \
+ -H 720 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ -v \
+ -o flf2v.webm
```
<video
@@ -88,52 +239,232 @@ To run the text encoder quantized, convert it once with sd-cli:
muted
style="max-width: 100%; height: auto;"></video>
-### LTX-2.3 spatial latent upscale
+#### LTX-2.3 spatial latent upscale
LTX spatial latent upscale runs a model-backed x2 latent upsampler between the low-resolution video pass and the high-resolution refine pass. `-W` and `-H` are the pre-upscale generation size; the spatial upsampler produces x2 latent dimensions.
Put `ltx-2.3-spatial-upscaler-x2-1.1.safetensors` under the directory passed to `--hires-upscalers-dir`, then use the model name without path or extension in `--hires-upscaler`.
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\ltx-2.3-22b-dev-UD-Q4_K_M.gguf `
+ --vae ..\models\vae\ltx-2.3-22b-dev_video_vae.safetensors `
+ --audio-vae ..\models\vae\ltx-2.3-22b-dev_audio_vae.safetensors `
+ --llm ..\models\text_encoders\gemma-3-12b-it-qat-UD-Q4_K_XL.gguf `
+ --embeddings-connectors ..\models\text_encoders\ltx-2.3-22b-dev_embeddings_connectors.safetensors `
+ --hires-upscalers-dir ..\models\latent_upscale_models `
+ -p "a lovely cat" `
+ -i ..\inputs\ernie_image\turbo_example.png `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ -W 640 `
+ -H 360 `
+ --video-frames 33 `
+ --hires-upscaler ltx-2.3-spatial-upscaler-x2-1.1 `
+ --hires `
+ --hires-steps 4 `
+ --offload-to-cpu `
+ -v `
+ -o hires_i2v.webm
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\ltx-2.3-22b-dev-UD-Q4_K_M.gguf --vae ..\models\vae\ltx-2.3-22b-dev_video_vae.safetensors --audio-vae ..\models\vae\ltx-2.3-22b-dev_audio_vae.safetensors --llm ..\models\text_encoders\gemma-3-12b-it-qat-UD-Q4_K_XL.gguf --embeddings-connectors ..\models\text_encoders\ltx-2.3-22b-dev_embeddings_connectors.safetensors --hires-upscalers-dir ..\models\latent_upscale_models --hires-upscaler ltx-2.3-spatial-upscaler-x2-1.1 --hires --hires-steps 4 -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -W 640 -H 360 --offload-to-cpu --video-frames 33 -i ..\assets\ernie_image\turbo_example.png -o hires_i2v.webm
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/ltx-2.3-22b-dev-UD-Q4_K_M.gguf \
+ --vae ../models/vae/ltx-2.3-22b-dev_video_vae.safetensors \
+ --audio-vae ../models/vae/ltx-2.3-22b-dev_audio_vae.safetensors \
+ --llm ../models/text_encoders/gemma-3-12b-it-qat-UD-Q4_K_XL.gguf \
+ --embeddings-connectors ../models/text_encoders/ltx-2.3-22b-dev_embeddings_connectors.safetensors \
+ --hires-upscalers-dir ../models/latent_upscale_models \
+ -p "a lovely cat" \
+ -i ../inputs/ernie_image/turbo_example.png \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ -W 640 \
+ -H 360 \
+ --video-frames 33 \
+ --hires-upscaler ltx-2.3-spatial-upscaler-x2-1.1 \
+ --hires \
+ --hires-steps 4 \
+ --offload-to-cpu \
+ -v \
+ -o hires_i2v.webm
```
By default, the hires refine pass uses the main sampler and scheduler, then trims the second-pass sigma schedule by `--hires-denoising-strength` (`0.7` by default). To reproduce a ComfyUI-style explicit refine schedule, pass custom hires sigmas:
-```
+**Windows (PowerShell) arguments**
+
+```text
--hires-sigmas "0.85,0.725,0.421875,0.0"
```
+**Linux/macOS arguments**
+
+```text
+--hires-sigmas 0.85,0.725,0.421875,0.0
+```
+
<video
src="../../assets/ltx2/hires_i2v.webm"
controls
muted
style="max-width: 100%; height: auto;"></video>
-### LTX-2.5 dev T2V
-
-```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\ltx-2.5-22b-dev-transformer-Q8_0.gguf --vae ..\models\vae\ltx-2.5-video-vae-conv-bf16.safetensors --audio-vae ..\models\vae\ltx-2.5-audio-vae-bf16.safetensors --llm ..\models\text_encoders\gemma4-12b-with-proj-ltx-2.5-Q8_0.gguf -p "A wide aerial shot of a red vintage convertible driving along a coastal cliff road at sunset, waves crashing below" --cfg-scale 3.0 --sampling-method euler -v -n "worst quality, low quality, blurry, distorted, artifacts" -W 1280 -H 720 --offload-to-cpu --video-frames 121 --fps 24 -o t2v.webm
+#### LTX-2.5 dev T2V
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\ltx-2.5-22b-dev-transformer-Q8_0.gguf `
+ --vae ..\models\vae\ltx-2.5-video-vae-conv-bf16.safetensors `
+ --audio-vae ..\models\vae\ltx-2.5-audio-vae-bf16.safetensors `
+ --llm ..\models\text_encoders\gemma4-12b-with-proj-ltx-2.5-Q8_0.gguf `
+ -p "A wide aerial shot of a red vintage convertible driving along a coastal cliff road at sunset, waves crashing below" `
+ -n "worst quality, low quality, blurry, distorted, artifacts" `
+ --cfg-scale 3.0 `
+ --sampling-method euler `
+ -W 1280 `
+ -H 720 `
+ --video-frames 121 `
+ --fps 24 `
+ --offload-to-cpu `
+ -v `
+ -o t2v.webm
```
-### LTX-2.5 dev I2V
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/ltx-2.5-22b-dev-transformer-Q8_0.gguf \
+ --vae ../models/vae/ltx-2.5-video-vae-conv-bf16.safetensors \
+ --audio-vae ../models/vae/ltx-2.5-audio-vae-bf16.safetensors \
+ --llm ../models/text_encoders/gemma4-12b-with-proj-ltx-2.5-Q8_0.gguf \
+ -p "A wide aerial shot of a red vintage convertible driving along a coastal cliff road at sunset, waves crashing below" \
+ -n "worst quality, low quality, blurry, distorted, artifacts" \
+ --cfg-scale 3.0 \
+ --sampling-method euler \
+ -W 1280 \
+ -H 720 \
+ --video-frames 121 \
+ --fps 24 \
+ --offload-to-cpu \
+ -v \
+ -o t2v.webm
+```
+#### LTX-2.5 dev I2V
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\ltx-2.5-22b-dev-transformer-Q8_0.gguf `
+ --vae ..\models\vae\ltx-2.5-video-vae-conv-bf16.safetensors `
+ --audio-vae ..\models\vae\ltx-2.5-audio-vae-bf16.safetensors `
+ --llm ..\models\text_encoders\gemma4-12b-with-proj-ltx-2.5-Q8_0.gguf `
+ -p "a lovely cat blinking slowly, gentle camera push in" `
+ -i ..\inputs\ernie_image\turbo_example.png `
+ --cfg-scale 3.0 `
+ --sampling-method euler `
+ -W 1280 `
+ -H 720 `
+ --video-frames 121 `
+ --offload-to-cpu `
+ -v `
+ -o i2v.webm
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\ltx-2.5-22b-dev-transformer-Q8_0.gguf --vae ..\models\vae\ltx-2.5-video-vae-conv-bf16.safetensors --audio-vae ..\models\vae\ltx-2.5-audio-vae-bf16.safetensors --llm ..\models\text_encoders\gemma4-12b-with-proj-ltx-2.5-Q8_0.gguf -p "a lovely cat blinking slowly, gentle camera push in" --cfg-scale 3.0 --sampling-method euler -v -W 1280 -H 720 --offload-to-cpu --video-frames 121 -i ..\assets\ernie_image\turbo_example.png -o i2v.webm
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/ltx-2.5-22b-dev-transformer-Q8_0.gguf \
+ --vae ../models/vae/ltx-2.5-video-vae-conv-bf16.safetensors \
+ --audio-vae ../models/vae/ltx-2.5-audio-vae-bf16.safetensors \
+ --llm ../models/text_encoders/gemma4-12b-with-proj-ltx-2.5-Q8_0.gguf \
+ -p "a lovely cat blinking slowly, gentle camera push in" \
+ -i ../inputs/ernie_image/turbo_example.png \
+ --cfg-scale 3.0 \
+ --sampling-method euler \
+ -W 1280 \
+ -H 720 \
+ --video-frames 121 \
+ --offload-to-cpu \
+ -v \
+ -o i2v.webm
```
-### LTX-2.5 spatial latent upscale
+#### LTX-2.5 spatial latent upscale
-Works exactly like the LTX-2.3 upscaler described below; put
+Works like the LTX-2.3 upscaler described above; put
`ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors` under `--hires-upscalers-dir` and
pass its name without path or extension to `--hires-upscaler`.
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\ltx-2.5-22b-dev-transformer-Q8_0.gguf `
+ --vae ..\models\vae\ltx-2.5-video-vae-conv-bf16.safetensors `
+ --audio-vae ..\models\vae\ltx-2.5-audio-vae-bf16.safetensors `
+ --llm ..\models\text_encoders\gemma4-12b-with-proj-ltx-2.5-Q8_0.gguf `
+ --hires-upscalers-dir ..\models\latent_upscale_models `
+ -p "a lovely cat" `
+ --cfg-scale 3.0 `
+ --sampling-method euler `
+ -W 640 `
+ -H 360 `
+ --video-frames 121 `
+ --hires-upscaler ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0 `
+ --hires `
+ --hires-steps 6 `
+ --offload-to-cpu `
+ -v `
+ -o hires_t2v.webm
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\ltx-2.5-22b-dev-transformer-Q8_0.gguf --vae ..\models\vae\ltx-2.5-video-vae-conv-bf16.safetensors --audio-vae ..\models\vae\ltx-2.5-audio-vae-bf16.safetensors --llm ..\models\text_encoders\gemma4-12b-with-proj-ltx-2.5-Q8_0.gguf --hires-upscalers-dir ..\models\latent_upscale_models --hires-upscaler ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0 --hires --hires-steps 6 -p "a lovely cat" --cfg-scale 3.0 --sampling-method euler -v -W 640 -H 360 --offload-to-cpu --video-frames 121 -o hires_t2v.webm
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/ltx-2.5-22b-dev-transformer-Q8_0.gguf \
+ --vae ../models/vae/ltx-2.5-video-vae-conv-bf16.safetensors \
+ --audio-vae ../models/vae/ltx-2.5-audio-vae-bf16.safetensors \
+ --llm ../models/text_encoders/gemma4-12b-with-proj-ltx-2.5-Q8_0.gguf \
+ --hires-upscalers-dir ../models/latent_upscale_models \
+ -p "a lovely cat" \
+ --cfg-scale 3.0 \
+ --sampling-method euler \
+ -W 640 \
+ -H 360 \
+ --video-frames 121 \
+ --hires-upscaler ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0 \
+ --hires \
+ --hires-steps 6 \
+ --offload-to-cpu \
+ -v \
+ -o hires_t2v.webm
```
-## Not implemented
+## Notes and limitations
+
+Not implemented:
- The diffusion video decoder (`ltx-2.5-video-vae-bf16.safetensors`). Use the conv VAE.
- The temporal latent upscaler and the duration head (`--auto-duration`); pass
- `--video-frames` explicitly.
\ No newline at end of file
+ `--video-frames` explicitly.
diff --git a/docs/models/mage_flow.md b/docs/models/mage_flow.md
index 5948f93..eaccdcf 100644
--- a/docs/models/mage_flow.md
+++ b/docs/models/mage_flow.md
@@ -2,32 +2,107 @@
[Mage-Flow](https://github.com/microsoft/Mage) uses a 4B native-resolution multimodal diffusion transformer, Qwen3-VL for text and image conditioning, and the 128-channel Mage-VAE. Both text-to-image and instruction-based image editing checkpoints are supported.
-## Download weights
+## Model files
-- Download Mage-Flow diffusion from https://huggingface.co/Comfy-Org/Mage-Flow/tree/main/diffusion_models
-- Download Mage-Flow vae from https://huggingface.co/Comfy-Org/Mage-Flow/tree/main/vae
-- Download Qwen3-VL 4B
- - safetensors: https://huggingface.co/Comfy-Org/Krea-2/tree/main/text_encoders
- - gguf: https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct-GGUF/tree/main
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Mage-Flow diffusion | Mage-Flow diffusion from [Download](https://huggingface.co/Comfy-Org/Mage-Flow/tree/main/diffusion_models) | `--diffusion-model` | Required |
+| Mage-Flow vae | Mage-Flow vae from [Download](https://huggingface.co/Comfy-Org/Mage-Flow/tree/main/vae) | `--vae` | Use matching VAE |
+| Qwen3-VL 4B | [Safetensors](https://huggingface.co/Comfy-Org/Krea-2/tree/main/text_encoders)<br>[GGUF](https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct-GGUF/tree/main) | `--llm` | Use matching text encoder |
-## Text-to-image
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Mage Flow (`mage-flow`) | `diffusion_model`, `llm`, `vae` |
+| Mage Flow Turbo (`mage-flow-turbo`) | `diffusion_model`, `llm`, `vae` |
+| Mage Flow Edit (`mage-flow-edit`) | `diffusion_model`, `llm`, `vae`, `llm_vision` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Text-to-image
Use 30 steps for Base models and 4 steps with `--cfg-scale 1` for Turbo models. Image dimensions must be multiples of 16; the official checkpoints are trained for native resolutions from 512 to 2048 pixels.
-```bash
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\Mage-Flow-Turbo.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --vae ..\models\vae\mage_vae.safetensors -p "a lovely cat holding a sign says 'mage.cpp'" --cfg-scale 1.0 --steps 4 -v --offload-to-cpu
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\Mage-Flow-Turbo.safetensors `
+ --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf `
+ --vae ..\models\vae\mage_vae.safetensors `
+ -p "a lovely cat holding a sign says 'mage.cpp'" `
+ --cfg-scale 1.0 `
+ --steps 4 `
+ --offload-to-cpu `
+ -v
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/Mage-Flow-Turbo.safetensors \
+ --llm ../models/text_encoders/Qwen3-VL-4B-Instruct-Q4_K_M.gguf \
+ --vae ../models/vae/mage_vae.safetensors \
+ -p "a lovely cat holding a sign says 'mage.cpp'" \
+ --cfg-scale 1.0 \
+ --steps 4 \
+ --offload-to-cpu \
+ -v
```
<img width="256" alt="Mage-Flow example" src="../../assets/mage_flow/example.png" />
-## Image editing
+#### Image editing
Mage-Flow-Edit accepts one or more reference images. The default `mage_flow` reference preset sends each image to both Qwen3-VL and the diffusion transformer, caps the VLM copy's longest edge at 384 pixels, and keeps the VAE copy at the requested output resolution.
For the Turbo edit checkpoint, use 4 steps and `--cfg-scale 1`.
-```bash
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\Mage-Flow-Edit.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --llm_vision ..\models\text_encoders\Qwen3-VL-4B-Instruct-mmproj-BF16.gguf --vae ..\models\vae\mage_vae.safetensors -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'mage.cpp'" --cfg-scale 4.0 --sampling-method euler -v --offload-to-cpu
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\Mage-Flow-Edit.safetensors `
+ --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf `
+ --llm_vision ..\models\text_encoders\Qwen3-VL-4B-Instruct-mmproj-BF16.gguf `
+ --vae ..\models\vae\mage_vae.safetensors `
+ -r ..\inputs\flux\flux1-dev-q8_0.png `
+ -p "change 'flux.cpp' to 'mage.cpp'" `
+ --cfg-scale 4.0 `
+ --sampling-method euler `
+ --offload-to-cpu `
+ -v
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/Mage-Flow-Edit.safetensors \
+ --llm ../models/text_encoders/Qwen3-VL-4B-Instruct-Q4_K_M.gguf \
+ --llm_vision ../models/text_encoders/Qwen3-VL-4B-Instruct-mmproj-BF16.gguf \
+ --vae ../models/vae/mage_vae.safetensors \
+ -r ../inputs/flux/flux1-dev-q8_0.png \
+ -p "change 'flux.cpp' to 'mage.cpp'" \
+ --cfg-scale 4.0 \
+ --sampling-method euler \
+ --offload-to-cpu \
+ -v
```
<img width="256" alt="Mage-Flow-Edit example" src="../../assets/mage_flow/edit_example.png" />
diff --git a/docs/models/ming_image.md b/docs/models/ming_image.md
index 8f48135..53dc7a9 100644
--- a/docs/models/ming_image.md
+++ b/docs/models/ming_image.md
@@ -2,23 +2,76 @@
[Ming-Image](https://github.com/inclusionAI/Ming-Image) 0.1 Design uses a 6B diffusion transformer (DiT), Ling-mini-2.0 for text conditioning, and the Ming-Image VAE. Text-to-image generation with RGBA output is supported.
-## Download weights
+## Model files
-- Download Ming-Image 0.1 Design DiT
- - safetensors: https://huggingface.co/Comfy-Org/Ming-Image/tree/main/diffusion_models
-- Download Ling-mini-2.0 BF16
- - safetensors: https://huggingface.co/Comfy-Org/Ming-Image/tree/main/text_encoders
-- Download Ming-Image VAE
- - safetensors: https://huggingface.co/Comfy-Org/Ming-Image/tree/main/vae
-- Download Ling tokenizer
- - tokenizer.json: https://huggingface.co/inclusionAI/Ming-Image-0.1-Design/blob/main/mllm/tokenizer.json
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Ming-Image 0.1 Design DiT | [Safetensors](https://huggingface.co/Comfy-Org/Ming-Image/tree/main/diffusion_models) | `--diffusion-model` | Required |
+| Ling-mini-2.0 BF16 | [Safetensors](https://huggingface.co/Comfy-Org/Ming-Image/tree/main/text_encoders) | `--llm` | Use matching text encoder |
+| Ming-Image VAE | [Safetensors](https://huggingface.co/Comfy-Org/Ming-Image/tree/main/vae) | `--vae` | Use matching VAE |
+| Ling tokenizer | tokenizer.json: [Download](https://huggingface.co/inclusionAI/Ming-Image-0.1-Design/blob/main/mllm/tokenizer.json) | `--tokenizer` | Required; match text encoder |
The example below uses `ming_image_0.1_design_bf16.safetensors` for the DiT. You can also use `ming_image_0.1_design_int8_convrot.safetensors` with [INT8 convrot support](../guides/int8_convrot.md). Use the BF16 text encoder.
-## Text-to-image
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Ming Image 0.1 (`ming-image`) | `diffusion_model`, `llm`, `tokenizer`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Text-to-image
Pass the Ling `tokenizer.json` with `--tokenizer` and use the matching Ming-Image VAE. Image dimensions must be multiples of 16. Save the output as PNG to preserve the alpha channel.
-```bash
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\ming_image_0.1_design_bf16.safetensors --llm ..\models\text_encoders\ming_image_0.1_ling_mini_2.0_bf16.safetensors --vae ..\models\vae\ming_image_vae_bf16.safetensors --tokenizer ..\models\text_encoders\tokenizer.json -p "A cheerful orange cat sticker, transparent background" --width 1024 --height 1024 --steps 12 --cfg-scale 1 --sampling-method euler -v --offload-to-cpu -o ming_image.png
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\ming_image_0.1_design_bf16.safetensors `
+ --llm ..\models\text_encoders\ming_image_0.1_ling_mini_2.0_bf16.safetensors `
+ --vae ..\models\vae\ming_image_vae_bf16.safetensors `
+ --tokenizer ..\models\tokenizers\tokenizer.json `
+ -p "A cheerful orange cat sticker, transparent background" `
+ --steps 12 `
+ --cfg-scale 1 `
+ --sampling-method euler `
+ --width 1024 `
+ --height 1024 `
+ --offload-to-cpu `
+ -v `
+ -o ming_image.png
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/ming_image_0.1_design_bf16.safetensors \
+ --llm ../models/text_encoders/ming_image_0.1_ling_mini_2.0_bf16.safetensors \
+ --vae ../models/vae/ming_image_vae_bf16.safetensors \
+ --tokenizer ../models/tokenizers/tokenizer.json \
+ -p "A cheerful orange cat sticker, transparent background" \
+ --steps 12 \
+ --cfg-scale 1 \
+ --sampling-method euler \
+ --width 1024 \
+ --height 1024 \
+ --offload-to-cpu \
+ -v \
+ -o ming_image.png
```
diff --git a/docs/models/minimax_h3.md b/docs/models/minimax_h3.md
index 40f3800..dc4c52e 100644
--- a/docs/models/minimax_h3.md
+++ b/docs/models/minimax_h3.md
@@ -23,14 +23,32 @@ connector, with `--llm`. Alternatively, pass Qwen3-VL-4B with `--llm` and the
with `--embeddings-connectors`. For example, replace the `--llm` argument in the
commands below with either:
-```sh
+**Windows (PowerShell) arguments**
+
+```text
--llm ..\models\text_encoders\p-h3-image_text_encoder_int8_convrot.safetensors
```
+**Linux/macOS arguments**
+
+```text
+--llm ../models/text_encoders/p-h3-image_text_encoder_int8_convrot.safetensors
+```
+
or:
-```sh
---llm ..\models\text_encoders\qwen3vl_4b.gguf --embeddings-connectors ..\models\text_encoders\p-h3-image_text_connector.safetensors
+**Windows (PowerShell) arguments**
+
+```text
+--llm ..\models\text_encoders\qwen3vl_4b.gguf `
+ --embeddings-connectors ..\models\text_encoders\p-h3-image_text_connector.safetensors
+```
+
+**Linux/macOS arguments**
+
+```text
+--llm ../models/text_encoders/qwen3vl_4b.gguf \
+ --embeddings-connectors ../models/text_encoders/p-h3-image_text_connector.safetensors
```
Reference-image and reference-video conditioning needs the matching encoder's
@@ -43,23 +61,78 @@ are detected from their weights.
### Download weights
-- Download minimax_h3_fl2va/minimax_h3_ref2va
- - safetensors: https://huggingface.co/Comfy-Org/MiniMax-H3/tree/main/diffusion_models
- - gguf: https://huggingface.co/leejet/MiniMax-H3-GGUF/tree/main
-- Download qwen3vl_32b_minimax_h3
- - safetensors: https://huggingface.co/Comfy-Org/MiniMax-H3/tree/main/text_encoders
- - gguf: https://huggingface.co/leejet/MiniMax-H3-GGUF/tree/main
-- Or download the P-H3-Image text encoder (Qwen3-VL-4B with the text connector)
- - safetensors: https://huggingface.co/PrunaAI/P-H3-Image-Comfy/tree/main/text_encoders
-- Download vae
- - safetensors: https://huggingface.co/Comfy-Org/MiniMax-H3/tree/main/vae
-- Download audio vae
- - safetensors: https://huggingface.co/Comfy-Org/MiniMax-H3/tree/main/vae
-
-## Text-to-audio-video
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| minimax_h3_fl2va/minimax_h3_ref2va | [Safetensors](https://huggingface.co/Comfy-Org/MiniMax-H3/tree/main/diffusion_models)<br>[GGUF](https://huggingface.co/leejet/MiniMax-H3-GGUF/tree/main) | `--diffusion-model` | Required |
+| qwen3vl_32b_minimax_h3 | [Safetensors](https://huggingface.co/Comfy-Org/MiniMax-H3/tree/main/text_encoders)<br>[GGUF](https://huggingface.co/leejet/MiniMax-H3-GGUF/tree/main) | `--llm` | Use matching text encoder |
+| P-H3-Image text encoder (Qwen3-VL-4B with the text connector) | [Safetensors](https://huggingface.co/PrunaAI/P-H3-Image-Comfy/tree/main/text_encoders) | `--llm` | Use matching text encoder |
+| vae | [Safetensors](https://huggingface.co/Comfy-Org/MiniMax-H3/tree/main/vae) | `--vae` | Use matching VAE |
+| audio vae | [Safetensors](https://huggingface.co/Comfy-Org/MiniMax-H3/tree/main/vae) | `--audio-vae` | Required |
+
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| MiniMax H3 FL2VA (`minimax-h3-fl2va`) | `diffusion_model`, `llm`, `llm_vision`, `embeddings_connectors`, `vae`, `tae`, `audio_vae` |
+| MiniMax H3 Ref2VA (`minimax-h3-ref2va`) | `diffusion_model`, `llm`, `llm_vision`, `embeddings_connectors`, `vae`, `tae`, `audio_vae` |
+| HyperFlow H3 Flash FL2VA (`hyperflow-h3-flash-fl2va`) | `diffusion_model`, `llm`, `llm_vision`, `embeddings_connectors`, `vae`, `tae`, `audio_vae` |
+| HyperFlow H3 Flash Ref2VA (`hyperflow-h3-flash-ref2va`) | `diffusion_model`, `llm`, `llm_vision`, `embeddings_connectors`, `vae`, `tae`, `audio_vae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Text-to-audio-video
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\minimax_h3_fl2va-Q4_K_M.gguf `
+ --vae ..\models\vae\minimax_h3_video_vae_fp16.safetensors `
+ --audio-vae ..\models\vae\minimax_h3_audio_vae_fp32.safetensors `
+ --llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf `
+ -p "A cute American Shorthair silver tabby kitten surfs on a tropical ocean wave, riding a white surfboard with the clear text 'sd.cpp' on it. Cinematic tracking shot, realistic water, bright sunlight, smooth motion, and consistent character appearance. Add upbeat tropical surf-rock background music with cheerful drums and guitar, synchronized with the kitten`’s energetic surfing." `
+ --cfg-scale 1.0 `
+ -W 864 `
+ -H 480 `
+ --fps 24 `
+ --video-frames 56 `
+ --rng cpu `
+ --offload-to-cpu `
+ -v
+```
+
+**Linux/macOS**
```sh
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\minimax_h3_fl2va-Q4_K_M.gguf --vae ..\models\vae\minimax_h3_video_vae_fp16.safetensors --audio-vae ..\models\vae\minimax_h3_audio_vae_fp32.safetensors --llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf -p "A cute American Shorthair silver tabby kitten surfs on a tropical ocean wave, riding a white surfboard with the clear text 'sd.cpp' on it. Cinematic tracking shot, realistic water, bright sunlight, smooth motion, and consistent character appearance. Add upbeat tropical surf-rock background music with cheerful drums and guitar, synchronized with the kitten’s energetic surfing." --cfg-scale 1.0 -v -W 864 -H 480 --offload-to-cpu --rng cpu --fps 24 --video-frames 56
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/minimax_h3_fl2va-Q4_K_M.gguf \
+ --vae ../models/vae/minimax_h3_video_vae_fp16.safetensors \
+ --audio-vae ../models/vae/minimax_h3_audio_vae_fp32.safetensors \
+ --llm ../models/text_encoders/qwen3vl_32b_minimax_h3-Q4_K_M.gguf \
+ -p "A cute American Shorthair silver tabby kitten surfs on a tropical ocean wave, riding a white surfboard with the clear text 'sd.cpp' on it. Cinematic tracking shot, realistic water, bright sunlight, smooth motion, and consistent character appearance. Add upbeat tropical surf-rock background music with cheerful drums and guitar, synchronized with the kitten’s energetic surfing." \
+ --cfg-scale 1.0 \
+ -W 864 \
+ -H 480 \
+ --fps 24 \
+ --video-frames 56 \
+ --rng cpu \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/minimax-h3/t2av.mp4 controls="controls" muted="muted" type="video/mp4"></video>
@@ -67,23 +140,99 @@ are detected from their weights.
Omitting `--audio-vae` still runs the joint diffusion model but produces video without a
decoded audio track.
-## First/last-frame conditioning
+#### First/last-frame conditioning
Add `--init-img` for I2VA, or both `--init-img` and `--end-img` for FL2VA:
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\minimax_h3_fl2va-Q4_K_M.gguf `
+ --vae ..\models\vae\minimax_h3_video_vae_fp16.safetensors `
+ --audio-vae ..\models\vae\minimax_h3_audio_vae_fp32.safetensors `
+ --llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf `
+ -p "a lovely cat" `
+ -i ..\inputs\ernie_image\turbo_example.png `
+ --cfg-scale 1.0 `
+ -W 864 `
+ -H 480 `
+ --fps 24 `
+ --video-frames 56 `
+ --rng cpu `
+ --offload-to-cpu `
+ -v
+```
+
+**Linux/macOS**
+
```sh
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\minimax_h3_fl2va-Q4_K_M.gguf --vae ..\models\vae\minimax_h3_video_vae_fp16.safetensors --audio-vae ..\models\vae\minimax_h3_audio_vae_fp32.safetensors --llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf -p "a lovely cat" -i ..\assets\ernie_image\turbo_example.png --cfg-scale 1.0 -v -W 864 -H 480 --offload-to-cpu --rng cpu --fps 24 --video-frames 56
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/minimax_h3_fl2va-Q4_K_M.gguf \
+ --vae ../models/vae/minimax_h3_video_vae_fp16.safetensors \
+ --audio-vae ../models/vae/minimax_h3_audio_vae_fp32.safetensors \
+ --llm ../models/text_encoders/qwen3vl_32b_minimax_h3-Q4_K_M.gguf \
+ -p "a lovely cat" \
+ -i ../inputs/ernie_image/turbo_example.png \
+ --cfg-scale 1.0 \
+ -W 864 \
+ -H 480 \
+ --fps 24 \
+ --video-frames 56 \
+ --rng cpu \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/minimax-h3/i2av.mp4 controls="controls" muted="muted" type="video/mp4"></video>
-## Reference-to-audio-video conditioning
+#### Reference-to-audio-video conditioning
Ref2VA accepts any combination of reference images, reference videos, paired
video soundtracks, and standalone audio references:
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\minimax_h3_ref2va_pruned-Q4_K_M.gguf `
+ --vae ..\models\vae\minimax_h3_video_vae_fp16.safetensors `
+ --audio-vae ..\models\vae\minimax_h3_audio_vae_fp32.safetensors `
+ --llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf `
+ -p "Use the cat from <Picture 1> as the main character. Keep the cat`’s appearance, fur color, facial features, and identity consistent with the reference image. Create a 2-second cinematic video: start with an extreme close-up shot of the cat`’s face, focusing on its cute expression and detailed fur texture. The camera slowly rotates around the cat`’s head, creating a dynamic reveal. Then smoothly pull back and zoom out to reveal the full scene: the cat is standing confidently on a surfboard, riding ocean waves. Water splashes around the board, sea breeze gently moves the cat`’s fur, and the cat maintains a cute and fearless expression while surfing. Smooth camera movement, cinematic orbit shot, seamless zoom-out transition, low-angle wide shot, realistic ocean environment, golden sunlight, dynamic waves, high-quality realistic style, natural motion, no distortion, keep the cat`’s identity unchanged." `
+ -r ..\inputs\ernie_image\turbo_example.png `
+ --cfg-scale 1.0 `
+ -W 864 `
+ -H 480 `
+ --fps 24 `
+ --video-frames 56 `
+ --rng cpu `
+ --offload-to-cpu `
+ -v
+```
+
+**Linux/macOS**
+
```sh
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\minimax_h3_ref2va_pruned-Q4_K_M.gguf --vae ..\models\vae\minimax_h3_video_vae_fp16.safetensors --audio-vae ..\models\vae\minimax_h3_audio_vae_fp32.safetensors --llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf -p "Use the cat from <Picture 1> as the main character. Keep the cat’s appearance, fur color, facial features, and identity consistent with the reference image. Create a 2-second cinematic video: start with an extreme close-up shot of the cat’s face, focusing on its cute expression and detailed fur texture. The camera slowly rotates around the cat’s head, creating a dynamic reveal. Then smoothly pull back and zoom out to reveal the full scene: the cat is standing confidently on a surfboard, riding ocean waves. Water splashes around the board, sea breeze gently moves the cat’s fur, and the cat maintains a cute and fearless expression while surfing. Smooth camera movement, cinematic orbit shot, seamless zoom-out transition, low-angle wide shot, realistic ocean environment, golden sunlight, dynamic waves, high-quality realistic style, natural motion, no distortion, keep the cat’s identity unchanged." -r ..\assets\ernie_image\turbo_example.png --cfg-scale 1.0 -v -W 864 -H 480 --offload-to-cpu --rng cpu --fps 24 --video-frames 56
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/minimax_h3_ref2va_pruned-Q4_K_M.gguf \
+ --vae ../models/vae/minimax_h3_video_vae_fp16.safetensors \
+ --audio-vae ../models/vae/minimax_h3_audio_vae_fp32.safetensors \
+ --llm ../models/text_encoders/qwen3vl_32b_minimax_h3-Q4_K_M.gguf \
+ -p "Use the cat from <Picture 1> as the main character. Keep the cat’s appearance, fur color, facial features, and identity consistent with the reference image. Create a 2-second cinematic video: start with an extreme close-up shot of the cat’s face, focusing on its cute expression and detailed fur texture. The camera slowly rotates around the cat’s head, creating a dynamic reveal. Then smoothly pull back and zoom out to reveal the full scene: the cat is standing confidently on a surfboard, riding ocean waves. Water splashes around the board, sea breeze gently moves the cat’s fur, and the cat maintains a cute and fearless expression while surfing. Smooth camera movement, cinematic orbit shot, seamless zoom-out transition, low-angle wide shot, realistic ocean environment, golden sunlight, dynamic waves, high-quality realistic style, natural motion, no distortion, keep the cat’s identity unchanged." \
+ -r ../inputs/ernie_image/turbo_example.png \
+ --cfg-scale 1.0 \
+ -W 864 \
+ -H 480 \
+ --fps 24 \
+ --video-frames 56 \
+ --rng cpu \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/minimax-h3/r2av.mp4 controls="controls" muted="muted" type="video/mp4"></video>
@@ -120,7 +269,7 @@ The C API exposes the same inputs through `ref_images`, `ref_videos`, and
`ref_audios` in `sd_vid_gen_params_t`. Each `sd_ref_video_t` supplies its own
frame rate and optional soundtrack; non-24-fps inputs are resampled internally.
-## Sol-H3-VAE decoding
+#### Sol-H3-VAE decoding
Pass a [Sol-H3-VAE checkpoint](https://huggingface.co/Comfy-Org/MiniMax-H3/tree/main/vae)
with `--vae` to use the distilled video decoder. The ComfyUI FP16 and INT8
@@ -138,7 +287,7 @@ frames, and overlap must be smaller than the tile. The last tile may be shorter.
Circular decoding requires spatial tiling on each circular axis, with a tile
size smaller than the input on that axis.
-## Latent hires second pass (two-stage sampling)
+#### Latent hires second pass (two-stage sampling)
MiniMax-H3 supports `--hires` with two interchangeable second-stage upscalers:
@@ -156,14 +305,86 @@ MiniMax-H3 supports `--hires` with two interchangeable second-stage upscalers:
Draft at a low megapixel count (e.g. 0.4 MP) and refine at a higher one
(e.g. 0.8 MP) instead of paying for the full resolution in every step:
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\minimax_h3_fl2va-Q4_K_M.gguf `
+ --vae ..\models\vae\minimax_h3_video_vae_fp16.safetensors `
+ --audio-vae ..\models\vae\minimax_h3_audio_vae_fp32.safetensors `
+ --llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf `
+ -p "a lovely cat" `
+ --cfg-scale 1.0 `
+ -W 864 `
+ -H 480 `
+ --video-frames 56 `
+ --rng cpu `
+ --hires `
+ --hires-upscaler "Latent (bicubic)" `
+ --hires-width 1216 `
+ --hires-height 672 `
+ --hires-steps 4 `
+ --hires-denoising-strength 0.4 `
+ --diffusion-fa `
+ --offload-to-cpu `
+ -v
+```
+
+**Linux/macOS**
+
```sh
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\minimax_h3_fl2va-Q4_K_M.gguf --vae ..\models\vae\minimax_h3_video_vae_fp16.safetensors --audio-vae ..\models\vae\minimax_h3_audio_vae_fp32.safetensors --llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf -p "a lovely cat" --cfg-scale 1.0 -v -W 864 -H 480 --diffusion-fa --offload-to-cpu --rng cpu --video-frames 56 --hires --hires-upscaler "Latent (bicubic)" --hires-width 1216 --hires-height 672 --hires-steps 4 --hires-denoising-strength 0.4
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/minimax_h3_fl2va-Q4_K_M.gguf \
+ --vae ../models/vae/minimax_h3_video_vae_fp16.safetensors \
+ --audio-vae ../models/vae/minimax_h3_audio_vae_fp32.safetensors \
+ --llm ../models/text_encoders/qwen3vl_32b_minimax_h3-Q4_K_M.gguf \
+ -p "a lovely cat" \
+ --cfg-scale 1.0 \
+ -W 864 \
+ -H 480 \
+ --video-frames 56 \
+ --rng cpu \
+ --hires \
+ --hires-upscaler "Latent (bicubic)" \
+ --hires-width 1216 \
+ --hires-height 672 \
+ --hires-steps 4 \
+ --hires-denoising-strength 0.4 \
+ --diffusion-fa \
+ --offload-to-cpu \
+ -v
```
or with the learned upscaler:
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen ... `
+ --hires-upscalers-dir ..\models\latent_upscale_models `
+ --hires `
+ --hires-upscaler h3-latent-upscaler-3d `
+ --hires-width 1216 `
+ --hires-height 672 `
+ --hires-steps 4 `
+ --hires-denoising-strength 0.4
+```
+
+**Linux/macOS**
+
```sh
-.\bin\Release\sd-cli.exe -M vid_gen ... --hires --hires-upscalers-dir ..\models\latent_upscale_models --hires-upscaler h3-latent-upscaler-3d --hires-width 1216 --hires-height 672 --hires-steps 4 --hires-denoising-strength 0.4
+./bin/sd-cli \
+ -M vid_gen ... \
+ --hires-upscalers-dir ../models/latent_upscale_models \
+ --hires \
+ --hires-upscaler h3-latent-upscaler-3d \
+ --hires-width 1216 \
+ --hires-height 672 \
+ --hires-steps 4 \
+ --hires-denoising-strength 0.4
```
Notes for this mode:
@@ -189,7 +410,34 @@ Notes for this mode:
fed into the network as an embedding, 1.2-2.0x is the trained domain, and
downscaling is rejected.
-## Shape and runtime notes
+#### HyperFlow H3 Flash
+
+[HyperFlow H3 Flash](https://huggingface.co/VideoRebirthAI/hyperflow-h3-flash)
+uses the shared components and input options described in this guide. Replace
+`--diffusion-model` with the matching HyperFlow FL2VA or Ref2VA checkpoint and
+use these sampling options:
+
+**Windows (PowerShell) arguments**
+
+```text
+--sampling-method euler `
+ --cfg-scale 1 `
+ --sigmas hyperflow-h3-flash-6
+```
+
+**Linux/macOS arguments**
+
+```text
+--sampling-method euler \
+ --cfg-scale 1 \
+ --sigmas hyperflow-h3-flash-6
+```
+
+Use `hyperflow-h3-flash-4` or `hyperflow-h3-flash-8` for 4 or 8 steps. These
+presets also work with `--hires-sigmas`; their length determines the step count.
+They already include video flow shift 12, so keep the default flow shift.
+
+## Notes and limitations
- Width and height are aligned upward to a multiple of 32.
- Frame count is aligned upward to the `17k + 5` grid, with a minimum of 5.
@@ -208,18 +456,3 @@ Notes for this mode:
block's working memory must also fit within the VRAM budget.
- The default video flow shift is 12. The audio stream is mapped internally to
its shift of 3, so the regular samplers can operate on the packed AV latent.
-
-## HyperFlow H3 Flash
-
-[HyperFlow H3 Flash](https://huggingface.co/VideoRebirthAI/hyperflow-h3-flash)
-uses the shared components and input options described in this guide. Replace
-`--diffusion-model` with the matching HyperFlow FL2VA or Ref2VA checkpoint and
-use these sampling options:
-
-```sh
---sampling-method euler --cfg-scale 1 --sigmas hyperflow-h3-flash-6
-```
-
-Use `hyperflow-h3-flash-4` or `hyperflow-h3-flash-8` for 4 or 8 steps. These
-presets also work with `--hires-sigmas`; their length determines the step count.
-They already include video flow shift 12, so keep the default flow shift.
diff --git a/docs/models/minimax_h3_image.md b/docs/models/minimax_h3_image.md
index 0a980cd..6a06236 100644
--- a/docs/models/minimax_h3_image.md
+++ b/docs/models/minimax_h3_image.md
@@ -32,38 +32,142 @@ VAE are incompatible. No audio VAE is needed.
### Download weights
-- Download minimax_h3_image_pruned
- - safetensors: https://huggingface.co/Comfy-Org/MiniMax-H3-Image/tree/main/diffusion_models
-- Download qwen3vl_32b_minimax_h3
- - safetensors: https://huggingface.co/Comfy-Org/MiniMax-H3-Image/tree/main/text_encoders
- - gguf: https://huggingface.co/leejet/MiniMax-H3-GGUF/tree/main
-- Or download the P-H3-Image text encoder (Qwen3-VL-4B with the text connector)
- - safetensors: https://huggingface.co/PrunaAI/P-H3-Image-Comfy/tree/main/text_encoders
-- Download vae
- - safetensors: https://huggingface.co/Comfy-Org/MiniMax-H3-Image/tree/main/vae
-
-## Text-to-image
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| minimax_h3_image_pruned | [Safetensors](https://huggingface.co/Comfy-Org/MiniMax-H3-Image/tree/main/diffusion_models) | `--diffusion-model` | Required |
+| qwen3vl_32b_minimax_h3 | [Safetensors](https://huggingface.co/Comfy-Org/MiniMax-H3-Image/tree/main/text_encoders)<br>[GGUF](https://huggingface.co/leejet/MiniMax-H3-GGUF/tree/main) | `--llm` | Use matching text encoder |
+| P-H3-Image text encoder (Qwen3-VL-4B with the text connector) | [Safetensors](https://huggingface.co/PrunaAI/P-H3-Image-Comfy/tree/main/text_encoders) | `--llm` | Use matching text encoder |
+| vae | [Safetensors](https://huggingface.co/Comfy-Org/MiniMax-H3-Image/tree/main/vae) | `--vae` | Use matching VAE |
+
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| MiniMax H3 Image (`minimax-h3-image`) | `diffusion_model`, `llm`, `llm_vision`, `embeddings_connectors`, `vae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Text-to-image
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\minimax_h3_image_pruned_bf16.safetensors `
+ --vae ..\models\vae\minimax_h3_image_vae_fp16.safetensors `
+ --llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf `
+ -p "A silver tabby kitten holding a sign reading 'sd.cpp', natural daylight" `
+ --cfg-scale 1.0 `
+ --steps 6 `
+ --sampling-method euler `
+ --sigmas minimax-h3-image `
+ -W 1024 `
+ -H 1024 `
+ --rng cpu `
+ --offload-to-cpu `
+ --diffusion-fa `
+ --vae-tiling `
+ -v
+```
+
+**Linux/macOS**
```sh
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\minimax_h3_image_pruned_bf16.safetensors --vae ..\models\vae\minimax_h3_image_vae_fp16.safetensors --llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf -p "A silver tabby kitten holding a sign reading 'sd.cpp', natural daylight" --cfg-scale 1.0 --steps 6 --sampling-method euler --sigmas minimax-h3-image -v -W 1024 -H 1024 --offload-to-cpu --rng cpu --diffusion-fa --vae-tiling
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/minimax_h3_image_pruned_bf16.safetensors \
+ --vae ../models/vae/minimax_h3_image_vae_fp16.safetensors \
+ --llm ../models/text_encoders/qwen3vl_32b_minimax_h3-Q4_K_M.gguf \
+ -p "A silver tabby kitten holding a sign reading 'sd.cpp', natural daylight" \
+ --cfg-scale 1.0 \
+ --steps 6 \
+ --sampling-method euler \
+ --sigmas minimax-h3-image \
+ -W 1024 \
+ -H 1024 \
+ --rng cpu \
+ --offload-to-cpu \
+ --diffusion-fa \
+ --vae-tiling \
+ -v
```
With the P-H3-Image text encoder, replace the `--llm` argument:
-```sh
+**Windows (PowerShell) arguments**
+
+```text
--llm ..\models\text_encoders\p-h3-image_text_encoder_int8_convrot.safetensors
```
+**Linux/macOS arguments**
+
+```text
+--llm ../models/text_encoders/p-h3-image_text_encoder_int8_convrot.safetensors
+```
+
Use Euler, CFG 1, and `--sigmas minimax-h3-image` for the model's six-step
schedule. The default discrete scheduler also produces this schedule with
`--steps 6`. Prompt expansion is not included.
-## Reference-image editing
+#### Reference-image editing
Add `--ref-image` (or `-r`) for reference-image editing:
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\minimax_h3_image_pruned_bf16.safetensors `
+ --vae ..\models\vae\minimax_h3_image_vae_fp16.safetensors `
+ --llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf `
+ -p "Edit <Picture 1>. Put a red scarf on the cat, preserving its face and the background." `
+ -r ..\inputs\ernie_image\turbo_example.png `
+ --cfg-scale 1.0 `
+ --steps 6 `
+ --sampling-method euler `
+ --sigmas minimax-h3-image `
+ -W 1024 `
+ -H 1024 `
+ --rng cpu `
+ --offload-to-cpu `
+ --diffusion-fa `
+ --vae-tiling `
+ -v
+```
+
+**Linux/macOS**
+
```sh
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\minimax_h3_image_pruned_bf16.safetensors --vae ..\models\vae\minimax_h3_image_vae_fp16.safetensors --llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf -p "Edit <Picture 1>. Put a red scarf on the cat, preserving its face and the background." -r ..\assets\ernie_image\turbo_example.png --cfg-scale 1.0 --steps 6 --sampling-method euler --sigmas minimax-h3-image -v -W 1024 -H 1024 --offload-to-cpu --rng cpu --diffusion-fa --vae-tiling
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/minimax_h3_image_pruned_bf16.safetensors \
+ --vae ../models/vae/minimax_h3_image_vae_fp16.safetensors \
+ --llm ../models/text_encoders/qwen3vl_32b_minimax_h3-Q4_K_M.gguf \
+ -p "Edit <Picture 1>. Put a red scarf on the cat, preserving its face and the background." \
+ -r ../inputs/ernie_image/turbo_example.png \
+ --cfg-scale 1.0 \
+ --steps 6 \
+ --sampling-method euler \
+ --sigmas minimax-h3-image \
+ -W 1024 \
+ -H 1024 \
+ --rng cpu \
+ --offload-to-cpu \
+ --diffusion-fa \
+ --vae-tiling \
+ -v
```
`--ref-image` can be repeated. Reference images are numbered in argument order
@@ -74,7 +178,7 @@ Reference images keep their aspect ratio. The text encoder sees a 1024-pixel
short edge, while VAE inputs use a short edge between 1024 and 2048 pixels.
Small references are enlarged and dimensions are rounded to multiples of 32.
-## Shape and runtime notes
+## Notes and limitations
- Width and height are aligned upward to a multiple of 32.
- Start at 1024 × 1024. Larger canvases and more references increase memory use.
diff --git a/docs/models/minit2i.md b/docs/models/minit2i.md
index 9f813a9..3e09b75 100644
--- a/docs/models/minit2i.md
+++ b/docs/models/minit2i.md
@@ -1,47 +1,86 @@
-# How to Use
+# MiniT2I
MiniT2I uses a MiniT2I diffusion transformer and `google/flan-t5-large` as the text encoder.
-## Download weights
+## Model files
-- Download MiniT2I diffusion model
- - safetensors: https://huggingface.co/MiniT2I/MiniT2I/tree/main/minit2i-b-16/transformer (`diffusion_pytorch_model.safetensors`)
-- Download flan-t5-large text encoder
- - safetensors: https://huggingface.co/google/flan-t5-large/tree/main (`model.safetensors`)
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| MiniT2I diffusion model | [Safetensors](https://huggingface.co/MiniT2I/MiniT2I/tree/main/minit2i-b-16/transformer) (`diffusion_pytorch_model.safetensors`) | `--diffusion-model` | Required |
+| flan-t5-large text encoder | [Safetensors](https://huggingface.co/google/flan-t5-large/tree/main) (`model.safetensors`) | `--t5xxl` | Required |
-## Examples
+## Usage
-### Mac Metal
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| MiniT2I (`minit2i`) | `diffusion_model`, `t5xxl` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### CUDA
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\minit2i\diffusion_pytorch_model.safetensors `
+ --t5xxl ..\models\text_encoders\flan-t5-large\model.safetensors `
+ --prompt "a cat" `
+ --steps 100 `
+ --cfg-scale 6 `
+ --sampling-method euler `
+ --width 512 `
+ --height 512 `
+ --seed 42 `
+ --output minit2i_cuda.png
```
+
+**Linux/macOS**
+
+```sh
./bin/sd-cli \
- --backend metal \
- --diffusion-model ../models/minit2i/diffusion_pytorch_model.safetensors \
- --t5xxl ../models/flan-t5-large/model.safetensors \
+ --diffusion-model ../models/diffusion_models/minit2i/diffusion_pytorch_model.safetensors \
+ --t5xxl ../models/text_encoders/flan-t5-large/model.safetensors \
--prompt "a cat" \
--steps 100 \
--cfg-scale 6 \
+ --sampling-method euler \
--width 512 \
--height 512 \
--seed 42 \
- --sampling-method euler \
- --rng cpu \
- --output minit2i_metal.png \
- --threads 8
+ --output minit2i_cuda.png
```
-### CUDA with diffusion flash attention
+#### macOS with Metal
-```
+**macOS (Metal)**
+
+```sh
./bin/sd-cli \
- --diffusion-model ../models/minit2i/diffusion_pytorch_model.safetensors \
- --t5xxl ../models/flan-t5-large/model.safetensors \
+ --diffusion-model ../models/diffusion_models/minit2i/diffusion_pytorch_model.safetensors \
+ --t5xxl ../models/text_encoders/flan-t5-large/model.safetensors \
--prompt "a cat" \
--steps 100 \
--cfg-scale 6 \
+ --sampling-method euler \
--width 512 \
--height 512 \
+ --rng cpu \
+ --threads 8 \
+ --backend metal \
--seed 42 \
- --sampling-method euler \
- --output minit2i_cuda.png
+ --output minit2i_metal.png
```
diff --git a/docs/models/moss_image.md b/docs/models/moss_image.md
index 67e7964..398b919 100644
--- a/docs/models/moss_image.md
+++ b/docs/models/moss_image.md
@@ -1,35 +1,106 @@
-# How to Use
+# MOSS-Image
MOSS-Image uses a 5B diffusion transformer, the FLUX.2 VAE, and Qwen3.5 9B as the LLM text encoder. Both Base and SFT are supported. Prompt enhancement is not included.
-## Download weights
+## Model files
-- Download MOSS-Image Base or SFT
- - safetensors: https://huggingface.co/Comfy-Org/MOSS-Image/tree/main/diffusion_models
- - gguf:
- - Base: https://huggingface.co/leejet/MOSS-Image-Base-GGUF/tree/main
- - SFT: https://huggingface.co/leejet/MOSS-Image-SFT-GGUF/tree/main
-- Download vae
- - safetensors: https://huggingface.co/Comfy-Org/MOSS-Image/tree/main/vae
-- Download Qwen3.5 9B
- - gguf: https://huggingface.co/unsloth/Qwen3.5-9B-GGUF/tree/main
-- Download `tokenizer.json`
- - https://huggingface.co/OpenMOSS-Team/MOSS-Image-Base/tree/main/tokenizer
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| MOSS-Image Base or SFT | [Safetensors](https://huggingface.co/Comfy-Org/MOSS-Image/tree/main/diffusion_models)<br>gguf:<br>Base: [Download](https://huggingface.co/leejet/MOSS-Image-Base-GGUF/tree/main)<br>SFT: [Download](https://huggingface.co/leejet/MOSS-Image-SFT-GGUF/tree/main) | `--diffusion-model` | Required |
+| vae | [Safetensors](https://huggingface.co/Comfy-Org/MOSS-Image/tree/main/vae) | `--vae` | Use matching VAE |
+| Qwen3.5 9B | [GGUF](https://huggingface.co/unsloth/Qwen3.5-9B-GGUF/tree/main) | `--llm` | Use matching text encoder |
+| `tokenizer.json` | [Download](https://huggingface.co/OpenMOSS-Team/MOSS-Image-Base/tree/main/tokenizer) | `--tokenizer` | Required; match text encoder |
Pass the external `tokenizer.json` with `--tokenizer`; Qwen3.5 uses a different vocabulary from the embedded Qwen tokenizer.
-## Examples
+## Usage
-### MOSS-Image Base
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| MOSS Image Base (`moss-image-base`) | `diffusion_model`, `llm`, `tokenizer`, `vae`, `tae` |
+| MOSS Image SFT (`moss-image-sft`) | `diffusion_model`, `llm`, `tokenizer`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### MOSS-Image Base
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\moss_image_base_int8_convrot_attn.safetensors `
+ --llm ..\models\text_encoders\Qwen3.5-9B-Q4_K_M.gguf `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ --tokenizer ..\models\tokenizers\tokenizer_qwen3.5.json `
+ -p "a lovely cat holding a sign says 'moss-image.cpp'" `
+ --cfg-scale 3.0 `
+ -H 1024 `
+ -W 1024 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\moss_image_base_int8_convrot_attn.safetensors --llm ..\models\text_encoders\Qwen3.5-9B-Q4_K_M.gguf --vae ..\models\vae\flux2_ae.safetensors --tokenizer ..\models\tokenizers\tokenizer_qwen3.5.json --cfg-scale 3.0 -p "a lovely cat holding a sign says 'moss-image.cpp'" -v --offload-to-cpu -H 1024 -W 1024
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/moss_image_base_int8_convrot_attn.safetensors \
+ --llm ../models/text_encoders/Qwen3.5-9B-Q4_K_M.gguf \
+ --vae ../models/vae/flux2_ae.safetensors \
+ --tokenizer ../models/tokenizers/tokenizer_qwen3.5.json \
+ -p "a lovely cat holding a sign says 'moss-image.cpp'" \
+ --cfg-scale 3.0 \
+ -H 1024 \
+ -W 1024 \
+ --offload-to-cpu \
+ -v
```
-### MOSS-Image SFT
+#### MOSS-Image SFT
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\moss_image_sft_int8_convrot_attn.safetensors `
+ --llm ..\models\text_encoders\Qwen3.5-9B-Q4_K_M.gguf `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ --tokenizer ..\models\tokenizers\tokenizer_qwen3.5.json `
+ -p "a lovely cat holding a sign says 'moss-image.cpp'" `
+ --cfg-scale 3.0 `
+ -H 1024 `
+ -W 1024 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\moss_image_sft_int8_convrot_attn.safetensors --llm ..\models\text_encoders\Qwen3.5-9B-Q4_K_M.gguf --vae ..\models\vae\flux2_ae.safetensors --tokenizer ..\models\tokenizers\tokenizer_qwen3.5.json --cfg-scale 3.0 -p "a lovely cat holding a sign says 'moss-image.cpp'" -v --offload-to-cpu -H 1024 -W 1024
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/moss_image_sft_int8_convrot_attn.safetensors \
+ --llm ../models/text_encoders/Qwen3.5-9B-Q4_K_M.gguf \
+ --vae ../models/vae/flux2_ae.safetensors \
+ --tokenizer ../models/tokenizers/tokenizer_qwen3.5.json \
+ -p "a lovely cat holding a sign says 'moss-image.cpp'" \
+ --cfg-scale 3.0 \
+ -H 1024 \
+ -W 1024 \
+ --offload-to-cpu \
+ -v
```
<img src="../../assets/moss/sft.png" />
diff --git a/docs/models/ovis_image.md b/docs/models/ovis_image.md
index fefb835..ddf6c21 100644
--- a/docs/models/ovis_image.md
+++ b/docs/models/ovis_image.md
@@ -1,19 +1,60 @@
-# How to Use
+# Ovis-Image
-## Download weights
+Ovis-Image generates images from text using an Ovis 2.5 encoder and the FLUX VAE.
-- Download Ovis-Image-7B
- - safetensors: https://huggingface.co/Comfy-Org/Ovis-Image/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/leejet/Ovis-Image-7B-GGUF
-- Download vae
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.1-schnell/tree/main
-- Download Ovis 2.5
- - safetensors: https://huggingface.co/Comfy-Org/Ovis-Image/tree/main/split_files/text_encoders
+## Model files
-## Examples
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Ovis-Image-7B | [Safetensors](https://huggingface.co/Comfy-Org/Ovis-Image/tree/main/split_files/diffusion_models)<br>[GGUF](https://huggingface.co/leejet/Ovis-Image-7B-GGUF) | `--diffusion-model` | Required |
+| vae | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.1-schnell/tree/main) | `--vae` | Use matching VAE |
+| Ovis 2.5 | [Safetensors](https://huggingface.co/Comfy-Org/Ovis-Image/tree/main/split_files/text_encoders) | `--llm` | Use matching text encoder |
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Ovis Image (`ovis-image`) | `diffusion_model`, `llm`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\ovis_image-Q4_0.gguf `
+ --vae ..\models\vae\ae.sft `
+ --llm ..\models\text_encoders\ovis_2.5.safetensors `
+ -p "a lovely cat" `
+ --cfg-scale 5.0 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ovis_image-Q4_0.gguf --vae ..\models\vae\ae.sft --llm ..\models\text_encoders\ovis_2.5.safetensors -p "a lovely cat" --cfg-scale 5.0 -v --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/ovis_image-Q4_0.gguf \
+ --vae ../models/vae/ae.sft \
+ --llm ../models/text_encoders/ovis_2.5.safetensors \
+ -p "a lovely cat" \
+ --cfg-scale 5.0 \
+ --offload-to-cpu \
+ -v
```
-<img alt="ovis image example" src="../../assets/ovis_image/example.png" />
\ No newline at end of file
+<img alt="ovis image example" src="../../assets/ovis_image/example.png" />
diff --git a/docs/models/p_h3_image.md b/docs/models/p_h3_image.md
index b712f4b..eed5784 100644
--- a/docs/models/p_h3_image.md
+++ b/docs/models/p_h3_image.md
@@ -1,45 +1,145 @@
-# How to Use
+# P-H3-Image
P-H3-Image supports text-to-image and reference-image editing. It uses a MiniMax-H3 diffusion transformer, a single-frame VAE, and either Qwen3-VL-4B with a text connector or the MiniMax-H3 Qwen3-VL-32B text encoder. Prompt enhancement is not included.
-## Download weights
+## Model files
-- Download P-H3-Image
- - safetensors: https://huggingface.co/PrunaAI/P-H3-Image-Comfy/tree/main/diffusion_models
-- Download P-H3-Image VAE
- - safetensors: https://huggingface.co/PrunaAI/P-H3-Image-Comfy/tree/main/vae
-- Download Qwen3-VL-4B with the text connector
- - https://huggingface.co/PrunaAI/P-H3-Image-Comfy/tree/main/text_encoders
-- Or download the MiniMax-H3 Qwen3-VL-32B text encoder
- - safetensors: https://huggingface.co/Comfy-Org/MiniMax-H3/tree/main/text_encoders
- - gguf: https://huggingface.co/leejet/MiniMax-H3-GGUF/tree/main
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| P-H3-Image | [Safetensors](https://huggingface.co/PrunaAI/P-H3-Image-Comfy/tree/main/diffusion_models) | `--diffusion-model` | Required |
+| P-H3-Image VAE | [Safetensors](https://huggingface.co/PrunaAI/P-H3-Image-Comfy/tree/main/vae) | `--vae` | Use matching VAE |
+| Qwen3-VL-4B with the text connector | [Download](https://huggingface.co/PrunaAI/P-H3-Image-Comfy/tree/main/text_encoders) | `--llm` | Use matching text encoder |
+| MiniMax-H3 Qwen3-VL-32B text encoder | [Safetensors](https://huggingface.co/Comfy-Org/MiniMax-H3/tree/main/text_encoders)<br>[GGUF](https://huggingface.co/leejet/MiniMax-H3-GGUF/tree/main) | `--llm` | Use matching text encoder |
Alternatively, reuse Qwen3-VL-4B, including its vision tower, with the [separate text connector](https://huggingface.co/PrunaAI/P-H3-Image/blob/main/text_connector/diffusion_pytorch_model.safetensors). Save the connector as `p-h3-image_text_connector.safetensors` and pass it with `--embeddings-connectors`.
The MiniMax-H3 Qwen3-VL-32B encoder does not need a text connector. To use it in
either example below, omit `--embeddings-connectors` and replace `--llm` with:
-```sh
+**Windows (PowerShell) arguments**
+
+```text
--llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf
```
+**Linux/macOS arguments**
+
+```text
+--llm ../models/text_encoders/qwen3vl_32b_minimax_h3-Q4_K_M.gguf
+```
+
Reference-image editing needs the matching encoder's vision tower. If stored
separately, pass it with `--llm_vision`.
Use the P-H3 image VAE; the MiniMax-H3 video VAE is not compatible. No audio VAE is needed.
-## Examples
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| P-H3-Image (`p-h3-image`) | `diffusion_model`, `llm`, `llm_vision`, `embeddings_connectors`, `vae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
-### Text-to-image
+### CLI
+#### Text-to-image
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\p-h3-image_int8_convrot.safetensors `
+ --llm ..\models\text_encoders\qwen3vl_4b_bf16.safetensors `
+ --embeddings-connectors ..\models\text_encoders\p-h3-image_text_connector.safetensors `
+ --vae ..\models\vae\p-h3-image_vae_bf16.safetensors `
+ -p "a lovely cat holding a sign says 'p-h3-image.cpp'" `
+ --cfg-scale 1.0 `
+ --steps 8 `
+ --sampling-method euler `
+ --sigmas p-h3-image `
+ -H 2912 `
+ -W 2912 `
+ --rng cpu `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\p-h3-image_int8_convrot.safetensors --llm ..\models\text_encoders\qwen3vl_4b_bf16.safetensors --embeddings-connectors ..\models\text_encoders\p-h3-image_text_connector.safetensors --vae ..\models\vae\p-h3-image_vae_bf16.safetensors --cfg-scale 1.0 --steps 8 --sampling-method euler --sigmas p-h3-image -p "a lovely cat holding a sign says 'p-h3-image.cpp'" -v --offload-to-cpu --rng cpu -H 2912 -W 2912
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/p-h3-image_int8_convrot.safetensors \
+ --llm ../models/text_encoders/qwen3vl_4b_bf16.safetensors \
+ --embeddings-connectors ../models/text_encoders/p-h3-image_text_connector.safetensors \
+ --vae ../models/vae/p-h3-image_vae_bf16.safetensors \
+ -p "a lovely cat holding a sign says 'p-h3-image.cpp'" \
+ --cfg-scale 1.0 \
+ --steps 8 \
+ --sampling-method euler \
+ --sigmas p-h3-image \
+ -H 2912 \
+ -W 2912 \
+ --rng cpu \
+ --offload-to-cpu \
+ -v
```
-### Image editing
+#### Image editing
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\p-h3-image_int8_convrot.safetensors `
+ --llm ..\models\text_encoders\qwen3vl_4b_bf16.safetensors `
+ --embeddings-connectors ..\models\text_encoders\p-h3-image_text_connector.safetensors `
+ --vae ..\models\vae\p-h3-image_vae_bf16.safetensors `
+ -r source.png `
+ -r reference.png `
+ -p "Edit <Picture 1>. Give the cat the scarf from <Picture 2>, preserving its face and the background." `
+ --cfg-scale 1.0 `
+ --steps 8 `
+ --sampling-method euler `
+ --sigmas p-h3-image `
+ -H 2912 `
+ -W 2912 `
+ --rng cpu `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\p-h3-image_int8_convrot.safetensors --llm ..\models\text_encoders\qwen3vl_4b_bf16.safetensors --embeddings-connectors ..\models\text_encoders\p-h3-image_text_connector.safetensors --vae ..\models\vae\p-h3-image_vae_bf16.safetensors --cfg-scale 1.0 --steps 8 --sampling-method euler --sigmas p-h3-image -r source.png -r reference.png -p "Edit <Picture 1>. Give the cat the scarf from <Picture 2>, preserving its face and the background." -v --offload-to-cpu --rng cpu -H 2912 -W 2912
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/p-h3-image_int8_convrot.safetensors \
+ --llm ../models/text_encoders/qwen3vl_4b_bf16.safetensors \
+ --embeddings-connectors ../models/text_encoders/p-h3-image_text_connector.safetensors \
+ --vae ../models/vae/p-h3-image_vae_bf16.safetensors \
+ -r source.png \
+ -r reference.png \
+ -p "Edit <Picture 1>. Give the cat the scarf from <Picture 2>, preserving its face and the background." \
+ --cfg-scale 1.0 \
+ --steps 8 \
+ --sampling-method euler \
+ --sigmas p-h3-image \
+ -H 2912 \
+ -W 2912 \
+ --rng cpu \
+ --offload-to-cpu \
+ -v
```
Reference images are numbered in argument order as `<Picture 1>`, `<Picture 2>`, and so on. A plain edit instruction gets `Edit <Picture 1>. ` prepended automatically. Prompts starting with `Edit <Picture N>` or `subject_definitions:` are used directly.
diff --git a/docs/models/photo_maker.md b/docs/models/photo_maker.md
index 1a3463e..1bc8ab3 100644
--- a/docs/models/photo_maker.md
+++ b/docs/models/photo_maker.md
@@ -1,53 +1,157 @@
-## Using PhotoMaker to personalize image generation
+# PhotoMaker
-You can use [PhotoMaker](https://github.com/TencentARC/PhotoMaker) to personalize generated images with your own ID.
+[PhotoMaker](https://github.com/TencentARC/PhotoMaker) personalizes image
+generation from identity images. It requires an SDXL base model.
-**NOTE**, currently PhotoMaker **ONLY** works with **SDXL** (any SDXL model files will work).
+## Model files
-Download PhotoMaker model file (in safetensor format) [here](https://huggingface.co/bssrdf/PhotoMaker). The official release of the model file (in .bin format) does not work with ```stablediffusion.cpp```.
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| SDXL checkpoint | [SDXL guide](sd.md) | `-m` / `--model` | Required; PhotoMaker is SDXL-only |
+| SDXL VAE | VAE compatible with the selected SDXL checkpoint | `--vae` | Use an override when required |
+| PhotoMaker v1 | [Safetensors weights](https://huggingface.co/bssrdf/PhotoMaker) | `--photo-maker` | For v1; the original .bin release is unsupported |
+| PhotoMaker v2 | [Safetensors weights](https://huggingface.co/bssrdf/PhotoMakerV2) | `--photo-maker` | Alternative to v1; requires precomputed face embeddings |
+| Identity images | A directory of portraits of the same person | `--pm-id-images-dir` | Required |
+| PhotoMaker v2 embeddings | `id_embeds.bin` from the preparation below | `--pm-id-embed-path` | Required for v2 |
-- Specify the PhotoMaker model path using the `--photo-maker PATH` parameter.
-- Specify the input images path using the `--pm-id-images-dir PATH` parameter.
+### Prepare PhotoMaker v2 embeddings
-In prompt, make sure you have a class word followed by the trigger word ```"img"``` (hard-coded for now). The class word could be one of ```"man, woman, girl, boy"```. If input ID images contain asian faces, add ```Asian``` before the class
-word.
+[PhotoMaker v2](https://github.com/TencentARC/PhotoMaker/blob/main/README_pmv2.md)
+adds a face-embedding preparation step. From the source repository root, run
+[`scripts/face_detect.py`](../../scripts/face_detect.py) on the identity image directory:
-Another PhotoMaker specific parameter:
+**Windows (PowerShell)**
-- ```--pm-style-strength (0-100)%```: default is 20 and 10-20 typically gets good results. Lower ratio means more faithfully following input ID (not necessarily better quality).
+```powershell
+python scripts\face_detect.py .\inputs\photomaker_examples\scarletthead_woman
+```
-Other parameters recommended for running Photomaker:
+**Linux/macOS**
-- ```--cfg-scale 5.0```
-- ```-H 1024```
-- ```-W 1024```
+```sh
+python scripts/face_detect.py ./inputs/photomaker_examples/scarletthead_woman
+```
-If on low memory GPUs (<= 8GB), recommend running with ```--vae-on-cpu``` option to get artifact free images.
+The script requires its Python dependencies, including PyTorch, NumPy, Diffusers,
+and InsightFace. It writes `id_embeds.bin` inside the input directory. Compute it
+once and reuse it for later generations. The image directory and `id_embeds.bin` stay under the repository's `inputs/`
+directory.
-Example:
+## Usage
-```bash
-bin/sd-cli -m ../models/sdxlUnstableDiffusers_v11.safetensors --vae ../models/sdxl_vae.safetensors --photo-maker ../models/photomaker-v1.safetensors --pm-id-images-dir ../assets/photomaker_examples/scarletthead_woman -p "a girl img, retro futurism, retro game art style but extremely beautiful, intricate details, masterpiece, best quality, space-themed, cosmic, celestial, stars, galaxies, nebulas, planets, science fiction, highly detailed" -n "realistic, photo-realistic, worst quality, greyscale, bad anatomy, bad hands, error, text" --cfg-scale 5.0 --sampling-method euler -H 1024 -W 1024 --pm-style-strength 10 --vae-on-cpu --steps 50
-```
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
-## PhotoMaker Version 2
+### Web UI
-[PhotoMaker Version 2 (PMV2)](https://github.com/TencentARC/PhotoMaker/blob/main/README_pmv2.md) has some key improvements. Unfortunately it has a very heavy dependency which makes running it a bit involved in ```SD.cpp```.
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
-Running PMV2 is now a two-step process:
+| Recipe | Component slots |
+| --- | --- |
+| SDXL PhotoMaker (`sdxl-photomaker`) | `model`, `photo_maker`, `vae`, `tae` |
-- Run a python script ```face_detect.py``` to obtain **id_embeds** for the given input images
-```
-python face_detect.py input_image_dir
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+Select the appropriate PhotoMaker weights and supply the identity images.
+PhotoMaker v2 also needs the prepared identity embedding.
+
+### CLI
+
+#### PhotoMaker Version 1
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\sdxlUnstableDiffusers_v11.safetensors `
+ --vae ..\models\vae\sdxl_vae.safetensors `
+ --photo-maker ..\models\photomaker\photomaker-v1.safetensors `
+ --pm-id-images-dir ..\inputs\photomaker_examples\scarletthead_woman `
+ -p "a girl img, retro futurism, retro game art style but extremely beautiful, intricate details, masterpiece, best quality, space-themed, cosmic, celestial, stars, galaxies, nebulas, planets, science fiction, highly detailed" `
+ -n "realistic, photo-realistic, worst quality, greyscale, bad anatomy, bad hands, error, text" `
+ --cfg-scale 5.0 `
+ --sampling-method euler `
+ --steps 50 `
+ -H 1024 `
+ -W 1024 `
+ --pm-style-strength 10 `
+ --vae-on-cpu
```
-An ```id_embeds.bin``` file will be generated in ```input_images_dir```
-**Note: this step is only needed to run once; the same ```id_embeds``` can be reused**
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -m ../models/checkpoints/sdxlUnstableDiffusers_v11.safetensors \
+ --vae ../models/vae/sdxl_vae.safetensors \
+ --photo-maker ../models/photomaker/photomaker-v1.safetensors \
+ --pm-id-images-dir ../inputs/photomaker_examples/scarletthead_woman \
+ -p "a girl img, retro futurism, retro game art style but extremely beautiful, intricate details, masterpiece, best quality, space-themed, cosmic, celestial, stars, galaxies, nebulas, planets, science fiction, highly detailed" \
+ -n "realistic, photo-realistic, worst quality, greyscale, bad anatomy, bad hands, error, text" \
+ --cfg-scale 5.0 \
+ --sampling-method euler \
+ --steps 50 \
+ -H 1024 \
+ -W 1024 \
+ --pm-style-strength 10 \
+ --vae-on-cpu
+```
-- Run the same command as in version 1 but replacing ```photomaker-v1.safetensors``` with ```photomaker-v2.safetensors```.
+#### PhotoMaker Version 2
+
+From the build directory, use the prepared identity embedding:
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\sdxlUnstableDiffusers_v11.safetensors `
+ --vae ..\models\vae\sdxl_vae.safetensors `
+ --photo-maker ..\models\photomaker\photomaker-v2.safetensors `
+ --pm-id-images-dir ..\inputs\photomaker_examples\scarletthead_woman `
+ --pm-id-embed-path ..\inputs\photomaker_examples\scarletthead_woman\id_embeds.bin `
+ -p "a girl img, retro futurism, retro game art style but extremely beautiful, intricate details, masterpiece, best quality, space-themed, cosmic, celestial, stars, galaxies, nebulas, planets, science fiction, highly detailed" `
+ -n "realistic, photo-realistic, worst quality, greyscale, bad anatomy, bad hands, error, text" `
+ --cfg-scale 5.0 `
+ --sampling-method euler `
+ --steps 50 `
+ -H 1024 `
+ -W 1024 `
+ --pm-style-strength 10 `
+ --vae-on-cpu
+```
- You can download ```photomaker-v2.safetensors``` from [here](https://huggingface.co/bssrdf/PhotoMakerV2)
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -m ../models/checkpoints/sdxlUnstableDiffusers_v11.safetensors \
+ --vae ../models/vae/sdxl_vae.safetensors \
+ --photo-maker ../models/photomaker/photomaker-v2.safetensors \
+ --pm-id-images-dir ../inputs/photomaker_examples/scarletthead_woman \
+ --pm-id-embed-path ../inputs/photomaker_examples/scarletthead_woman/id_embeds.bin \
+ -p "a girl img, retro futurism, retro game art style but extremely beautiful, intricate details, masterpiece, best quality, space-themed, cosmic, celestial, stars, galaxies, nebulas, planets, science fiction, highly detailed" \
+ -n "realistic, photo-realistic, worst quality, greyscale, bad anatomy, bad hands, error, text" \
+ --cfg-scale 5.0 \
+ --sampling-method euler \
+ --steps 50 \
+ -H 1024 \
+ -W 1024 \
+ --pm-style-strength 10 \
+ --vae-on-cpu
+```
-- All the command line parameters from Version 1 remain the same for Version 2 plus one extra pointing to a valid ```id_embeds``` file: --pm-id-embed-path [path_to__id_embeds.bin]
+## Options
+The prompt must include a class word followed by the trigger word `img`, for
+example `a girl img`. Class words include `man`, `woman`, `girl`, and `boy`.
+For Asian identity images, the original workflow places `Asian` before the class word.
+`--pm-style-strength` accepts 0-100 and defaults to 20. The original examples use
+10-20; lower values follow the source identity more closely. Use CFG 5 and
+1024 x 1024 as in the example. On GPUs with 8 GB or less, `--vae-on-cpu` can help
+with VAE memory usage.
diff --git a/docs/models/pid.md b/docs/models/pid.md
index 26cec92..7f89f1b 100644
--- a/docs/models/pid.md
+++ b/docs/models/pid.md
@@ -1,33 +1,87 @@
-# How to Use
+# PiD
PiD is NVIDIA's Pixel Diffusion Decoder. It replaces the usual VAE decode or decode-then-upscale path with a pixel-space diffusion decoder conditioned on a
source latent and text prompt. Both the original PiD checkpoints and PiD 1.5 are supported.
In stable-diffusion.cpp, PiD currently runs as an image edit pipeline: provide a reference image with `-r`/`--ref-image`, encode that image with a matching VAE, then let the PiD diffusion model decode/upscale directly to RGB.
-## Download weights
-
-- Download PiD
- - safetensors: https://huggingface.co/Comfy-Org/PixelDiT/tree/main/diffusion_models
-- Download Gemma 2 2B
- - safetensors: https://huggingface.co/Comfy-Org/PixelDiT/tree/main/text_encoders
-- Download Gemma 2 2B tokenizer.json
- - https://huggingface.co/google/gemma-2-2b/tree/main
-- Download the VAE that matches the PiD checkpoint backbone
- - safetensors: https://huggingface.co/nvidia/PiD/tree/main/checkpoints
- - Flux / Z-Image PiD: use the Flux VAE and pass `--vae-format flux`
- - SD3 PiD: use the SD3 VAE and pass `--vae-format sd3`
- - Flux.2 PiD: use the Flux.2 VAE and pass `--vae-format flux2`
- - Qwen-Image PiD: use the Qwen-Image 2D VAE and pass `--vae-format wan`
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| PiD | [Safetensors](https://huggingface.co/Comfy-Org/PixelDiT/tree/main/diffusion_models) | `--diffusion-model` | Required |
+| Gemma 2 2B | [Safetensors](https://huggingface.co/Comfy-Org/PixelDiT/tree/main/text_encoders) | `--llm` | Use matching text encoder |
+| Gemma 2 2B tokenizer.json | [Download](https://huggingface.co/google/gemma-2-2b/tree/main) | `--tokenizer` | Required; match text encoder |
+| VAE that matches the PiD checkpoint backbone | [Safetensors](https://huggingface.co/nvidia/PiD/tree/main/checkpoints)<br>Flux / Z-Image PiD: use the Flux VAE and pass `--vae-format flux`<br>SD3 PiD: use the SD3 VAE and pass `--vae-format sd3`<br>Flux.2 PiD: use the Flux.2 VAE and pass `--vae-format flux2`<br>Qwen-Image PiD: use the Qwen-Image 2D VAE and pass `--vae-format wan` | `--vae` | Use matching VAE |
The official PiD model card should be checked before use. At the time of the initial PiD release, the official weights are under the NSCLv1 non-commercial license.
PiD and PiD 1.5 require an external Gemma 2 `tokenizer.json` matching the text encoder checkpoint. Save it as `tokenizer_gemma2.json` and pass it with `--tokenizer`; the tokenizer is not embedded in sd.cpp. See [JSON tokenizers](../guides/tokenizers.md) for CLI and C API usage.
-## Examples
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| PiD (Flux / Z-Image VAE) (`pid`) | `diffusion_model`, `llm`, `tokenizer`, `vae` |
+| PiD 1.5 (Flux / Z-Image VAE) (`pid-15`) | `diffusion_model`, `llm`, `tokenizer`, `vae` |
+| PiD (SD3 VAE) (`pid-sd3`) | `diffusion_model`, `llm`, `tokenizer`, `vae` |
+| PiD 1.5 (SD3 VAE) (`pid-15-sd3`) | `diffusion_model`, `llm`, `tokenizer`, `vae` |
+| PiD (Flux.2 VAE) (`pid-flux2`) | `diffusion_model`, `llm`, `tokenizer`, `vae` |
+| PiD 1.5 (Flux.2 VAE) (`pid-15-flux2`) | `diffusion_model`, `llm`, `tokenizer`, `vae` |
+| PiD (Qwen Image VAE) (`pid-qwen-image`) | `diffusion_model`, `llm`, `tokenizer`, `vae` |
+| PiD 1.5 (Qwen Image VAE) (`pid-15-qwen-image`) | `diffusion_model`, `llm`, `tokenizer`, `vae` |
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\pid_flux1_512_to_2048_4step_bf16.safetensors `
+ --llm ..\models\text_encoders\gemma_2_2b_it_elm_bf16.safetensors `
+ --tokenizer ..\models\tokenizers\tokenizer_gemma2.json `
+ --vae ..\models\vae\ae.sft `
+ --vae-format flux `
+ -p "a lovely cat" `
+ -r ..\inputs\ernie_image\turbo_example.png `
+ --cfg-scale 1.0 `
+ --steps 4 `
+ -H 2048 `
+ -W 2048 `
+ --rng cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\pid_flux1_512_to_2048_4step_bf16.safetensors --llm "..\models\text_encoders\gemma_2_2b_it_elm_bf16.safetensors" --tokenizer ..\models\tokenizers\tokenizer_gemma2.json --vae ..\models\vae\ae.sft --vae-format flux --cfg-scale 1.0 -p "a lovely cat" -r ..\assets\ernie_image\turbo_example.png -v --steps 4 -H 2048 -W 2048 --rng cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/pid_flux1_512_to_2048_4step_bf16.safetensors \
+ --llm ../models/text_encoders/gemma_2_2b_it_elm_bf16.safetensors \
+ --tokenizer ../models/tokenizers/tokenizer_gemma2.json \
+ --vae ../models/vae/ae.sft \
+ --vae-format flux \
+ -p "a lovely cat" \
+ -r ../inputs/ernie_image/turbo_example.png \
+ --cfg-scale 1.0 \
+ --steps 4 \
+ -H 2048 \
+ -W 2048 \
+ --rng cpu \
+ -v
```
Before:
@@ -37,7 +91,7 @@ Before:
After:
<img width="1024" alt="PiD example" src="../../assets/pid/example.png" />
-## Notes
+## Notes and limitations
- `-r`/`--ref-image` is required. PiD uses the first reference image as the source latent condition.
- `--vae-format` should match the VAE latent layout used by the PiD checkpoint. This is important when using standalone VAE files because the PiD diffusion
diff --git a/docs/models/pixart.md b/docs/models/pixart.md
index f9386ab..336e1ee 100644
--- a/docs/models/pixart.md
+++ b/docs/models/pixart.md
@@ -1,31 +1,74 @@
-# How to Use
+# PixArt
You can run PixArt-α / PixArt-Σ with stable-diffusion.cpp.
PixArt is a DiT-based text-to-image model family conditioned by a T5-XXL text
encoder and a 4-channel VAE: SDXL-style for PixArt-Σ and SD1.x-style for PixArt-α.
-## Download weights
-
-- Download the transformer (diffusion model)
- - PixArt-Σ XL-2 1024-MS: https://huggingface.co/PixArt-alpha/PixArt-Sigma-XL-2-1024-MS/tree/main/transformer
- - PixArt-α XL-2 1024-MS: https://huggingface.co/PixArt-alpha/PixArt-XL-2-1024-MS/tree/main/transformer
-- Download the T5-XXL text encoder
- - safetensors: https://huggingface.co/PixArt-alpha/PixArt-Sigma-XL-2-1024-MS/tree/main/text_encoder
-- Download the VAE
- - PixArt-Σ: https://huggingface.co/PixArt-alpha/PixArt-Sigma-XL-2-1024-MS/tree/main/vae
- - PixArt-α: https://huggingface.co/PixArt-alpha/PixArt-XL-2-1024-MS/tree/main/vae
- - Use the VAE matching the checkpoint's latent space. For TAE decoding or
- preview, use TAESDXL for PixArt-Σ and TAESD for PixArt-α.
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| transformer (diffusion model) | PixArt-Σ XL-2 1024-MS: [Download](https://huggingface.co/PixArt-alpha/PixArt-Sigma-XL-2-1024-MS/tree/main/transformer)<br>PixArt-α XL-2 1024-MS: [Download](https://huggingface.co/PixArt-alpha/PixArt-XL-2-1024-MS/tree/main/transformer) | `--diffusion-model` | Required |
+| T5-XXL text encoder | [Safetensors](https://huggingface.co/PixArt-alpha/PixArt-Sigma-XL-2-1024-MS/tree/main/text_encoder) | `--t5xxl` | Required |
+| VAE | PixArt-Σ: [Download](https://huggingface.co/PixArt-alpha/PixArt-Sigma-XL-2-1024-MS/tree/main/vae)<br>PixArt-α: [Download](https://huggingface.co/PixArt-alpha/PixArt-XL-2-1024-MS/tree/main/vae)<br>Use the VAE matching the checkpoint's latent space. For TAE decoding or<br>preview, use TAESDXL for PixArt-Σ and TAESD for PixArt-α. | `--vae` | Use matching VAE |
+
- Tokenizer: the T5 vocabulary is embedded; no extra tokenizer file is needed.
-## Examples
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| PixArt Alpha XL 512 (`pixart-alpha-512`) | `diffusion_model`, `t5xxl`, `vae`, `tae` |
+| PixArt Alpha XL 1024 (`pixart-alpha-1024`) | `diffusion_model`, `t5xxl`, `vae`, `tae` |
+| PixArt Sigma XL 1024 (`pixart-sigma`) | `diffusion_model`, `t5xxl`, `vae`, `tae` |
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\pixart_sigma_xl2_1024_ms.safetensors `
+ --t5xxl ..\models\text_encoders\t5xxl.safetensors `
+ --vae ..\models\vae\pixart_vae.safetensors `
+ -p "a lovely cat" `
+ --cfg-scale 4.5 `
+ --steps 20 `
+ -W 1024 `
+ -H 1024 `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\pixart_sigma_xl2_1024_ms.safetensors --t5xxl ..\models\text_encoders\t5xxl.safetensors --vae ..\models\vae\pixart_vae.safetensors -p "a lovely cat" --cfg-scale 4.5 -W 1024 -H 1024 --steps 20 -v
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/pixart_sigma_xl2_1024_ms.safetensors \
+ --t5xxl ../models/text_encoders/t5xxl.safetensors \
+ --vae ../models/vae/pixart_vae.safetensors \
+ -p "a lovely cat" \
+ --cfg-scale 4.5 \
+ --steps 20 \
+ -W 1024 \
+ -H 1024 \
+ -v
```
-## Notes
+## Notes and limitations
- The VAE scaling factor defaults to `0.13025` for PixArt-Σ. PixArt-α
checkpoints with resolution micro-condition weights use `0.18215`.
diff --git a/docs/models/pulid.md b/docs/models/pulid.md
index 469a273..188fbb8 100644
--- a/docs/models/pulid.md
+++ b/docs/models/pulid.md
@@ -1,57 +1,24 @@
-# PuLID-Flux face-identity preservation
-
-stable-diffusion.cpp supports the [PuLID-Flux](https://github.com/ToTheBeginning/PuLID)
-identity-injection technique on top of Flux.1 (schnell or dev) models.
-Given a single source portrait, PuLID-Flux produces new generations that
-preserve the source person's face across arbitrary scenes, poses, and
-prompts.
-
-Unlike PhotoMaker (which extracts the identity inside the inference
-process from a directory of images), PuLID-Flux's identity extractor is
-a heavy stack (insightface ArcFace + EVA-CLIP-L + IDFormer encoder) that
-is impractical to port to C++/ggml. To keep this implementation small and
-cross-vendor, **stable-diffusion.cpp consumes a precomputed identity
-embedding** produced by an external Python tool that runs once per source
-portrait. Everything downstream of that one-shot extraction is C++ and
-runs on any backend (Vulkan, CUDA, Metal, ROCm, CPU).
-
-## Architecture summary
-
-The PuLID-Flux contribution to the Flux denoise loop is a stack of 20
-small cross-attention modules (`PerceiverAttentionCA`) inserted between
-the Flux transformer blocks:
-
-- After every 2nd of the 19 double-stream blocks (10 hook points)
-- After every 4th of the 38 single-stream blocks (10 hook points)
-
-Each cross-attention layer takes the current image tokens as query, the
-32-token / 2048-dim identity embedding as key+value, and adds its output
-(scaled by `id_weight`, typically 1.0) back to the image tokens.
-
-## Required weights
-
-Three files in addition to the standard Flux weight set:
-
-1. **Flux base** (transformer + VAE + clip_l + t5xxl) -- exactly as
- [FLUX.1 guide](flux.md) describes.
-2. **PuLID weights** -- download from
- [guozinan/PuLID](https://huggingface.co/guozinan/PuLID):
- - `pulid_flux_v0.9.0.safetensors` or `pulid_flux_v0.9.1.safetensors`
- (recommended; this implementation is verified against v0.9.1)
- - **v1.1 (`pulid_v1.1.safetensors`) is NOT yet supported** -- it uses
- renamed keys (`id_adapter_attn_layers.*` instead of `pulid_ca.*`)
- and possibly different module structure. Future PR.
-3. **Identity embedding (.pulidembd)** -- produced by the precompute
- tool below.
-
-## Precompute the identity embedding
-
-The precompute tool runs the PyTorch identity-extraction stack on a
-single portrait image and writes the resulting `(32, 2048)` embedding
-to a `.pulidembd` binary file (about 131 KB). Run it once per source
+# PuLID-Flux
+
+[PuLID-Flux](https://github.com/ToTheBeginning/PuLID) preserves a source portrait
+identity while generating new images with FLUX.1 dev or schnell. Compute the
+identity embedding once with the external Python tool, then reuse it.
+
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| FLUX.1 base components | [FLUX.1 guide](flux.md) | `--diffusion-model`, `--vae`, `--clip_l`, `--t5xxl` | Required; dev or schnell |
+| PuLID v0.9.x weights | [guozinan/PuLID](https://huggingface.co/guozinan/PuLID) | `--pulid-weights` | v0.9.1 is the tested version; v1.1 is unsupported |
+| Identity embedding | `source.pulidembd` from preparation below | `--pulid-id-embedding` | Required for identity preservation |
+
+### Prepare the identity embedding
+
+The precompute tool extracts an identity embedding from a single portrait
+and writes it to a `.pulidembd` file. Run it once per source
person; the same file is reused for any number of generations.
-A reference Python script is provided alongside this docs file at
+Use
[`scripts/pulid_extract_id.py`](../../scripts/pulid_extract_id.py). It
requires:
- A working CUDA / CPU PyTorch stack
@@ -62,50 +29,91 @@ requires:
`pulid/pipeline_flux.py`) and `eva_clip/` package on `PYTHONPATH`; `flux/`
is not needed for embedding extraction
-Run it as:
+From the source repository root, run:
-```
-python pulid_extract_id.py \
- --portrait /path/to/source-photo.jpg \
- --pulid-weights /path/to/pulid_flux_v0.9.1.safetensors \
- --out /path/to/source.pulidembd
-```
+**Windows (PowerShell)**
-## Format (gguf)
+```powershell
+python scripts\pulid_extract_id.py --portrait .\inputs\source-photo.jpg --pulid-weights .\models\pulid\pulid_flux_v0.9.1.safetensors --out .\inputs\source.pulidembd
+```
-The embedding is a standard **gguf** container holding a single tensor:
+**Linux/macOS**
-```
-tensor name : "pulid_id"
-shape : [token_dim, num_tokens] (ggml order; typically [2048, 32])
-type : F16 (also accepts F32 / BF16)
-metadata : general.architecture = "pulid", pulid.version = 1
+```sh
+python scripts/pulid_extract_id.py --portrait ./inputs/source-photo.jpg --pulid-weights ./models/pulid/pulid_flux_v0.9.1.safetensors --out ./inputs/source.pulidembd
```
-stable-diffusion.cpp loads it with the normal gguf reader
-(`gguf_init_from_file`) and converts to fp32 at load time -- no bespoke
-parser. Total file size for the typical (32, 2048, fp16) case is ~131 KB.
+The script writes the embedding to the repository's `inputs/` directory.
+The examples below read the same file from the build directory.
+
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| FLUX.1 dev PuLID (`flux1-pulid`) | `diffusion_model`, `clip_l`, `t5xxl`, `pulid_weights`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\flux1-schnell-Q4_K_S.gguf `
+ --vae ..\models\vae\ae.safetensors `
+ --clip_l ..\models\text_encoders\clip_l.safetensors `
+ --t5xxl ..\models\text_encoders\t5xxl_fp16.safetensors `
+ --pulid-weights ..\models\pulid\pulid_flux_v0.9.1.safetensors `
+ --pulid-id-embedding ..\inputs\source.pulidembd `
+ -p "candid photograph of a young woman on a beach at sunset" `
+ --cfg-scale 1.0 `
+ --sampling-method euler `
+ --steps 4 `
+ -W 512 `
+ -H 512 `
+ --pulid-id-weight 1.0 `
+ --clip-on-cpu `
+ --seed 42 `
+ -o out.png
+```
-## Command-line usage
+**Linux/macOS**
-```
-.\bin\Release\sd-cli.exe \
- --diffusion-model models\flux1-schnell-Q4_K_S.gguf \
- --vae models\ae.safetensors \
- --clip_l models\clip_l.safetensors \
- --t5xxl models\t5xxl_fp16.safetensors \
- --pulid-weights models\pulid_flux_v0.9.1.safetensors \
- --pulid-id-embedding source.pulidembd \
- --pulid-id-weight 1.0 \
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/flux1-schnell-Q4_K_S.gguf \
+ --vae ../models/vae/ae.safetensors \
+ --clip_l ../models/text_encoders/clip_l.safetensors \
+ --t5xxl ../models/text_encoders/t5xxl_fp16.safetensors \
+ --pulid-weights ../models/pulid/pulid_flux_v0.9.1.safetensors \
+ --pulid-id-embedding ../inputs/source.pulidembd \
-p "candid photograph of a young woman on a beach at sunset" \
- --cfg-scale 1.0 --sampling-method euler --steps 4 -W 512 -H 512 \
- --seed 42 --clip-on-cpu \
+ --cfg-scale 1.0 \
+ --sampling-method euler \
+ --steps 4 \
+ -W 512 \
+ -H 512 \
+ --pulid-id-weight 1.0 \
+ --clip-on-cpu \
+ --seed 42 \
-o out.png
```
For Flux Dev (instead of Schnell), add `--guidance 3.5` and `--steps 20`.
-## Flags
+## Options
| Flag | Purpose |
|----------------------------|-------------------------------------------------------------------|
@@ -113,84 +121,79 @@ For Flux Dev (instead of Schnell), add `--guidance 3.5` and `--steps 20`.
| `--pulid-id-embedding <p>` | Path to a `.pulidembd` binary produced by the precompute tool. |
| `--pulid-id-weight <f>` | Identity-injection strength. Typical 0.7-1.2; default 1.0. |
-All three flags must be set together to activate PuLID. Setting only
-`--pulid-weights` (no embedding) loads the weights but disables injection
-at runtime. Setting `--pulid-id-weight 0` zeros out the contribution
-(useful for falsification testing: outputs should be byte-identical to
-a no-PuLID run with the same seed).
+Supply both the PuLID weights and identity embedding to activate identity
+conditioning. `--pulid-id-weight` defaults to 1.0; set it to 0 to disable identity
+injection. Loading `--pulid-weights` without an embedding leaves identity
+conditioning inactive.
-## Memory budget
+### Backend selection
-At 512x512, 4 steps (Schnell), the 20 cross-attention layers add roughly
-10% to denoise time and almost nothing to peak VRAM. Tested on a 12 GB
-consumer card alongside Flux Schnell Q4 GGUF + CPU-offloaded clip_l and
-t5xxl + GPU-resident VAE.
+The standard `--backend` flag works as documented. Common patterns:
-At 1024x1024 with Flux Dev Q4 + 20 steps + PuLID, the VAE decode compute
-buffer doesn't fit on a 12 GB card even with `--vae-on-cpu`. Workaround:
-explicitly route VAE to the CPU backend instead of the offload flag:
+**Windows (PowerShell) arguments**
-```
+```text
+# AMD Vulkan
--backend "diffusion=vulkan0,vae=cpu"
-```
-The `--vae-on-cpu` flag offloads VAE weights but leaves the compute graph
-on the default backend; this is existing stable-diffusion.cpp behavior,
-not a PuLID-specific issue. Documented here because anyone running PuLID
-at 1024 will hit it.
+# NVIDIA Vulkan
+--backend "diffusion=vulkan1,vae=cpu"
-## Backend selection
+# CUDA
+--backend "diffusion=cuda0,vae=cpu"
+```
-The standard `--backend` flag works as documented. Common patterns:
+**Linux/macOS arguments**
-```
+```text
# AMD Vulkan
---backend "diffusion=vulkan0,vae=cpu"
+--backend diffusion=vulkan0,vae=cpu
# NVIDIA Vulkan
---backend "diffusion=vulkan1,vae=cpu"
+--backend diffusion=vulkan1,vae=cpu
# CUDA
---backend "diffusion=cuda0,vae=cpu"
+--backend diffusion=cuda0,vae=cpu
```
The PuLID cross-attention layers run on the same backend as the main
diffusion model. They have not yet been independently profiled on every
backend; only Vulkan and CPU have been tested by the original contributor.
-## Verification
-
-A three-way SHA-256 check is the recommended sanity test when bringing up
-a new combination of model + backend + hardware:
-
-| Run | Expected hash relation |
-|----------------------------------------------|------------------------------------|
-| A: no `--pulid-*` flags | baseline |
-| B: PuLID flags, `--pulid-id-weight 0.0` | **byte-identical to A** |
-| C: PuLID flags, `--pulid-id-weight 1.0` | **different from A,B**, preserves source identity |
-
-If A and C differ but A and B differ too, the injection is allocating
-or computing something even at zero weight -- likely a bug.
-
-## Limitations / not yet supported
-
-- **`--skip-layers` (skip-layer-guidance / SLG) combined with PuLID** is not
- supported. The `pulid_ca` index advances per non-skipped block, so a
- skipped block silently misaligns the cross-attention weight assignment
- vs. the trained intervals. The reference PyTorch implementation does
- not have SLG either, so there is no well-defined behavior to emulate.
- Use either feature alone.
-- **PuLID v1.1 weights** (`pulid_v1.1.safetensors`, renamed key layout).
-- **Multiple ID images.** The reference PyTorch implementation can fuse
- several portraits into one embedding for stronger identity. This
- implementation accepts a single embedding produced from one or more
- images by the external precompute tool.
-- **Negative-prompt branch of CFG.** PuLID only injects on the positive
- conditioning path in the published reference, and the implementation
- here follows that. Flux's distilled guidance doesn't run a separate
- uncond branch in normal use, so this matters only for `--true-cfg`
- workflows that aren't standard for Flux.
-- **Backends other than Vulkan and CPU** are untested by the original
- contributor. The implementation is pure-ggml and should work on CUDA,
- ROCm, and Metal, but verification by users on those backends is
- welcomed.
+## Notes and limitations
+
+PuLID v1.1 weights are unsupported. Use PuLID and skip-layer guidance
+(`--skip-layers`) separately. One precomputed identity embedding is accepted per
+request; prepare it using the external tool. Identity conditioning is applied
+to the positive CFG branch.
+
+At 512x512, 4 steps (Schnell), the 20 cross-attention layers add roughly
+10% to denoise time and almost nothing to peak VRAM. Tested on a 12 GB
+consumer card alongside Flux Schnell Q4 GGUF + CPU-offloaded clip_l and
+t5xxl + GPU-resident VAE.
+
+At 1024x1024 with Flux Dev Q4 + 20 steps + PuLID, the VAE decode compute
+buffer doesn't fit on a 12 GB card even with `--vae-on-cpu`. Workaround:
+explicitly route VAE to the CPU backend instead of the offload flag:
+
+**Windows (PowerShell) arguments**
+
+```text
+--backend "diffusion=vulkan0,vae=cpu"
+```
+
+**Linux/macOS arguments**
+
+```text
+--backend diffusion=vulkan0,vae=cpu
+```
+
+The `--vae-on-cpu` flag offloads VAE weights but leaves the compute graph
+on the default backend; this is existing stable-diffusion.cpp behavior,
+not a PuLID-specific issue. Documented here because anyone running PuLID
+at 1024 will hit it.
+
+The original contributor tested Vulkan and CPU. Other backends were not
+validated in those tests. See [backend selection](../guides/backend.md) for
+device placement. Internal format details and validation procedures are in the
+[PuLID developer notes](../development/pulid.md).
diff --git a/docs/models/qwen_image.md b/docs/models/qwen_image.md
index 0fd1fa2..030f2f7 100644
--- a/docs/models/qwen_image.md
+++ b/docs/models/qwen_image.md
@@ -1,23 +1,68 @@
-# How to Use
+# Qwen Image
-## Download weights
+Qwen Image generates images from text using Qwen2.5-VL and the Qwen Image VAE.
-- Download Qwen Image
- - safetensors: https://huggingface.co/Comfy-Org/Qwen-Image_ComfyUI/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/QuantStack/Qwen-Image-GGUF/tree/main
-- Download vae
- - safetensors: https://huggingface.co/Comfy-Org/Qwen-Image_ComfyUI/tree/main/split_files/vae
-- Download qwen_2.5_vl 7b
- - safetensors: https://huggingface.co/Comfy-Org/Qwen-Image_ComfyUI/tree/main/split_files/text_encoders
- - gguf: https://huggingface.co/mradermacher/Qwen2.5-VL-7B-Instruct-GGUF/tree/main
+## Model files
-## Examples
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Qwen Image | [Safetensors](https://huggingface.co/Comfy-Org/Qwen-Image_ComfyUI/tree/main/split_files/diffusion_models)<br>[GGUF](https://huggingface.co/QuantStack/Qwen-Image-GGUF/tree/main) | `--diffusion-model` | Required |
+| vae | [Safetensors](https://huggingface.co/Comfy-Org/Qwen-Image_ComfyUI/tree/main/split_files/vae) | `--vae` | Use matching VAE |
+| qwen_2.5_vl 7b | [Safetensors](https://huggingface.co/Comfy-Org/Qwen-Image_ComfyUI/tree/main/split_files/text_encoders)<br>[GGUF](https://huggingface.co/mradermacher/Qwen2.5-VL-7B-Instruct-GGUF/tree/main) | `--llm` | Use matching text encoder |
-```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\qwen-image-Q8_0.gguf --vae ..\models\vae\qwen_image_vae.safetensors --llm ..\models\text_encoders\Qwen2.5-VL-7B-Instruct-Q8_0.gguf -p '一个穿着"QWEN"标志的T恤的中国美女正拿着黑色的马克笔面相镜头微笑。她身后的玻璃板上手写体写着 “一、Qwen-Image的技术路线： 探索视觉生成基础模型的极限，开创理解与生成一体化的未来。二、Qwen-Image的模型特色：1、复杂文字渲染。支持中英渲染、自动布局； 2、精准图像编辑。支持文字编辑、物体增减、风格变换。三、Qwen-Image的未来愿景：赋能专业内容创作、助力生成式AI发展。”' --cfg-scale 2.5 --sampling-method euler -v --offload-to-cpu -H 1024 -W 1024 --flow-shift 3
-```
+## Usage
-<img alt="qwen example" src="../../assets/qwen/example.png" />
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Qwen Image (`qwen-image`) | `diffusion_model`, `llm`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+### CLI
+**Windows (PowerShell)**
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\qwen-image-Q8_0.gguf `
+ --vae ..\models\vae\qwen_image_vae.safetensors `
+ --llm ..\models\text_encoders\Qwen2.5-VL-7B-Instruct-Q8_0.gguf `
+ -p "一个穿着`"QWEN`"标志的T恤的中国美女正拿着黑色的马克笔面相镜头微笑。她身后的玻璃板上手写体写着 `“一、Qwen-Image的技术路线： 探索视觉生成基础模型的极限，开创理解与生成一体化的未来。二、Qwen-Image的模型特色：1、复杂文字渲染。支持中英渲染、自动布局； 2、精准图像编辑。支持文字编辑、物体增减、风格变换。三、Qwen-Image的未来愿景：赋能专业内容创作、助力生成式AI发展。`”" `
+ --cfg-scale 2.5 `
+ --sampling-method euler `
+ --flow-shift 3 `
+ -H 1024 `
+ -W 1024 `
+ --offload-to-cpu `
+ -v
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/qwen-image-Q8_0.gguf \
+ --vae ../models/vae/qwen_image_vae.safetensors \
+ --llm ../models/text_encoders/Qwen2.5-VL-7B-Instruct-Q8_0.gguf \
+ -p "一个穿着\"QWEN\"标志的T恤的中国美女正拿着黑色的马克笔面相镜头微笑。她身后的玻璃板上手写体写着 “一、Qwen-Image的技术路线： 探索视觉生成基础模型的极限，开创理解与生成一体化的未来。二、Qwen-Image的模型特色：1、复杂文字渲染。支持中英渲染、自动布局； 2、精准图像编辑。支持文字编辑、物体增减、风格变换。三、Qwen-Image的未来愿景：赋能专业内容创作、助力生成式AI发展。”" \
+ --cfg-scale 2.5 \
+ --sampling-method euler \
+ --flow-shift 3 \
+ -H 1024 \
+ -W 1024 \
+ --offload-to-cpu \
+ -v
+```
+
+<img alt="qwen example" src="../../assets/qwen/example.png" />
diff --git a/docs/models/qwen_image_2.1.md b/docs/models/qwen_image_2.1.md
index d708ae8..7ddfda5 100644
--- a/docs/models/qwen_image_2.1.md
+++ b/docs/models/qwen_image_2.1.md
@@ -1,99 +1,201 @@
-# How to Use
+# Qwen Image 2.1
Qwen Image 2.1 supports text-to-image generation and image editing, using Qwen3-VL-8B as the text encoder and its own VAE.
-## Download weights
+## Model files
-- Download Qwen Image 2.1
- - safetensors: https://huggingface.co/Comfy-Org/Qwen-Image-2.1/tree/main/diffusion_models
- - gguf: https://huggingface.co/leejet/Qwen-Image-2.1-GGUF/tree/main
-- Download vae
- - safetensors: https://huggingface.co/Comfy-Org/Qwen-Image-2.1/tree/main/vae
-- Download Qwen3-VL-8B-Instruct
- - safetensors (BF16 or INT8 convrot): https://huggingface.co/Comfy-Org/Qwen-Image-2.1/tree/main/text_encoders
- - gguf: https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct-GGUF/tree/main
- - For image editing with a GGUF text encoder, also download `mmproj-Qwen3VL-8B-Instruct-F16.gguf` from the same repository and pass it with `--llm_vision`.
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Qwen Image 2.1 | [Safetensors](https://huggingface.co/Comfy-Org/Qwen-Image-2.1/tree/main/diffusion_models)<br>[GGUF](https://huggingface.co/leejet/Qwen-Image-2.1-GGUF/tree/main) | `--diffusion-model` | Required |
+| vae | [Safetensors](https://huggingface.co/Comfy-Org/Qwen-Image-2.1/tree/main/vae) | `--vae` | Use matching VAE |
+| Qwen3-VL-8B-Instruct | safetensors (BF16 or INT8 convrot): [Safetensors](https://huggingface.co/Comfy-Org/Qwen-Image-2.1/tree/main/text_encoders)<br>[GGUF](https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct-GGUF/tree/main)<br>For image editing with a GGUF text encoder, also download `mmproj-Qwen3VL-8B-Instruct-F16.gguf` from the same repository and pass it with `--llm_vision`. | `--llm` | Use matching text encoder |
Use `qwen_image_2.1_vae_bf16.safetensors` with this model. The earlier Qwen Image and Wan 2.2 VAE weights are not interchangeable with the Qwen Image 2.1 VAE weights.
For faster encoding, decoding, or previews, see [TAEQI2.1](taesd.md#qwen-image-21-taeqi21).
-## Examples
+## Usage
-Run the following commands from the build directory. Use image dimensions divisible by 32. The resolution-dependent flow schedule is selected automatically.
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
-### Text to image
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Qwen Image 2.1 (`qwen-image-21`) | `diffusion_model`, `llm`, `llm_vision`, `vae`, `tae` |
+| Qwen Image 2.1 Turbo (`qwen-image-21-turbo`) | `diffusion_model`, `llm`, `llm_vision`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+Use image dimensions divisible by 32. The resolution-dependent flow schedule is selected automatically.
+
+#### Text to image
+
+**Windows (PowerShell)**
```powershell
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\qwen_image_2.1_int8_convrot.safetensors --vae ..\models\vae\qwen_image_2.1_vae_bf16.safetensors --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf -p "a lovely cat holding a sign says 'qwen2.1.cpp'" --cfg-scale 6.0 --sampling-method euler -v --offload-to-cpu -o qwen_image_2.1.png
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\qwen_image_2.1_int8_convrot.safetensors `
+ --vae ..\models\vae\qwen_image_2.1_vae_bf16.safetensors `
+ --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf `
+ -p "a lovely cat holding a sign says 'qwen2.1.cpp'" `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ --offload-to-cpu `
+ -v `
+ -o qwen_image_2.1.png
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/qwen_image_2.1_int8_convrot.safetensors \
+ --vae ../models/vae/qwen_image_2.1_vae_bf16.safetensors \
+ --llm ../models/text_encoders/Qwen3VL-8B-Instruct-Q4_K_M.gguf \
+ -p "a lovely cat holding a sign says 'qwen2.1.cpp'" \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ --offload-to-cpu \
+ -v \
+ -o qwen_image_2.1.png
```
<img alt="Qwen Image 2.1 example" src="../../assets/qwen/qwen_image_2.1.png" />
To use GGUF diffusion weights, set `--diffusion-model` to the path of a file such as `qwen_image_2.1-Q4_K.gguf`.
-### Turbo
+#### Turbo
For [Qwen Image 2.1 Turbo](https://huggingface.co/Qwen/Qwen-Image-2.1-Turbo), use the Turbo diffusion weights and select its fixed 8-step sigma schedule with `--sigmas qwen-image-2.1-turbo`. For example, add these sampling options to the command above:
+**Windows (PowerShell) arguments**
+
```text
---sigmas qwen-image-2.1-turbo --steps 8 --cfg-scale 1.0 --sampling-method euler
+--sigmas qwen-image-2.1-turbo `
+ --steps 8 `
+ --cfg-scale 1.0 `
+ --sampling-method euler
+```
+
+**Linux/macOS arguments**
+
+```text
+--sigmas qwen-image-2.1-turbo \
+ --steps 8 \
+ --cfg-scale 1.0 \
+ --sampling-method euler
```
The preset is equivalent to `--sigmas 1.0,0.978453,0.95418,0.926626,0.89508,0.845148,0.704534,0.414568,0.0`. It only supplies the sigma values; CFG scale and sampling method remain independently configurable. As with an explicit sigma list, the sigma count determines the actual number of sampling steps. The same preset name is also accepted by `--hires-sigmas` for the highres fix second pass.
-### Image editing
+#### Image editing
Pass the reference image with `-r` and describe the edit in `-p`. Vision weights are required; the example below loads them separately with `--llm_vision`.
+**Windows (PowerShell)**
+
```powershell
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\qwen_image_2.1_int8_convrot.safetensors --vae ..\models\vae\qwen_image_2.1_vae_bf16.safetensors --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf --llm_vision ..\models\text_encoders\Qwen3VL-8B-Instruct-mmproj-BF16.gguf -r ..\assets\qwen\qwen_image_2.1.png -p "change 'qwen2.1.cpp' to 'sd.cpp'" --cfg-scale 6.0 --sampling-method euler -v --offload-to-cpu -o qwen_image_2.1_edit.png
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\qwen_image_2.1_int8_convrot.safetensors `
+ --vae ..\models\vae\qwen_image_2.1_vae_bf16.safetensors `
+ --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf `
+ --llm_vision ..\models\text_encoders\Qwen3VL-8B-Instruct-mmproj-BF16.gguf `
+ -r ..\inputs\qwen\qwen_image_2.1.png `
+ -p "change 'qwen2.1.cpp' to 'sd.cpp'" `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ --offload-to-cpu `
+ -v `
+ -o qwen_image_2.1_edit.png
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/qwen_image_2.1_int8_convrot.safetensors \
+ --vae ../models/vae/qwen_image_2.1_vae_bf16.safetensors \
+ --llm ../models/text_encoders/Qwen3VL-8B-Instruct-Q4_K_M.gguf \
+ --llm_vision ../models/text_encoders/Qwen3VL-8B-Instruct-mmproj-BF16.gguf \
+ -r ../inputs/qwen/qwen_image_2.1.png \
+ -p "change 'qwen2.1.cpp' to 'sd.cpp'" \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ --offload-to-cpu \
+ -v \
+ -o qwen_image_2.1_edit.png
```
For multiple reference images, repeat `-r` in the desired order, for example `-r first.png -r second.png`.
-### Prefix cache
+#### Alpha channel
-By default, the first denoising call for each fixed condition saves the text and reference-image keys and values from every transformer layer. Later calls only compute the target-image tokens. Positive and negative conditions use separate caches, which are released when sampling ends.
+This model supports alpha channel output. As the model determines whether to output a regular image or with transparency through the prompt, according to [official recommendation](https://github.com/QwenLM/Qwen-Image-2.1#transparent-image-generation-rgba), use the following prompt format for better results:
-Set `qwen_image_2_1_prefix_cache_type` in `--model-args` to `auto` or a type name using the same parser and case-sensitive names as `--type`:
+> `This is an RGBA image with transparency. <your description>. The image has alpha channel and the background is transparent.`
-- `auto` (default): use FP16 only when Flash Attention is enabled, Sage Attention is disabled, the attention scale is unchanged, and every attention operation in the cache-writing or cache-reading graph selects Flash Attention after backend support checks. If an operation falls back, rebuild the prefix in FP32 before executing and keep FP32 for the rest of that sampling run.
-- `f32`: always store FP32 keys and values.
-- `f16`: always store FP16 keys and values, including with ordinary attention or custom attention scaling. This saves cache memory but can introduce additional rounding error.
-- Other types, such as `bf16`, `q4_1`, `q5_0`, `q5_1`, `q8_0`, `q4_K`, `q6_K`, `iq4_nl`, and `iq4_xs`: use the requested storage type if the ggml build provides runtime conversion to and from FP32. Quantization is lossy and must be selected explicitly; `auto` never selects a quantized type.
+Since transparency is decided by the prompt rather than by the input or an explicit switch, the same format applies equally to editing, whether or not the reference image itself has an alpha channel. Note that alpha is kept only in `.png` and `.webp` outputs; saving as `.jpg` drops the transparency.
-Cache data is packed into contiguous rows of `hidden_size` elements before conversion, so 256-element quantization blocks work with the model's 128-element attention heads without padding. The type's block size must divide `hidden_size`. Unknown types, types lacking runtime conversion (for example `q8_1` and several IQ formats), and incompatible block sizes are ignored with a warning, leaving the previous setting or the default `auto` unchanged.
+Here are some examples ran with Q6_K quantization:
+| Input | Prompt | Output |
+| --- | --- | --- |
+|  | This is an RGBA image with transparency. Replace the text "BLOOM" with "Qwen Image 2.1", keeping the same font of the original text. The image has alpha channel and the background is transparent. |  |
+|  | This is an RGBA image with transparency. Remove the background of the image, keeping only the text and cat. The image has alpha channel and the background is transparent. |  |
-For example, use `--model-args qwen_image_2_1_prefix_cache_type=q8_0` to enable 8-bit cache storage. Cached keys and values are converted back to the attention input type before concatenating with the current target tokens. This reduces persistent cache memory; attention working buffers still use floating-point values, and conversion adds work on each step. Backends without the required conversion operations use the existing CPU fallback.
+#### Other features
-For the default 32-layer model, a prefix of 4096 tokens takes approximately the following memory per condition, excluding weights, working buffers, and allocation overhead:
+Other features of the model could be found on the [model card from QwenLM/Qwen-Image-2.1 repo](https://github.com/QwenLM/Qwen-Image-2.1), including 2 finetuned prompt rewriting Qwen3.5-9B model.
-| Cache type | Memory |
-| --- | ---: |
-| `f32` | 4 GiB |
-| `f16` | 2 GiB |
-| `q8_0` | 1.0625 GiB |
-| `q4_0` | 0.5625 GiB |
+## Options
-The runner accounts for the cache when checking the memory budget. If a cached execution runs out of memory, it releases the prefix caches, disables caching for the rest of that sampling run, and retries the full sequence once. Per-step conditioning extensions currently use the full-sequence path.
+### Prefix cache
-Disable this optimization with `--model-args qwen_image_2_1_prefix_cache=false`. It reuses step-independent activations; numerical results can still differ slightly because the matrix sizes change.
+Qwen Image 2.1 caches the text and reference-image condition between denoising
+steps. Positive and negative conditions use separate caches, released when
+sampling ends.
-### Alpha channel
+Set `qwen_image_2_1_prefix_cache_type` through `--model-args`:
-This model supports alpha channel output. As the model determines whether to output a regular image or with transparency through the prompt, according to [official recommendation](https://github.com/QwenLM/Qwen-Image-2.1#transparent-image-generation-rgba), use the following prompt format for better results:
+- `auto` (default): selects FP16 when the Flash Attention path supports it,
+ otherwise FP32. Sage Attention and custom attention scaling use FP32 in this
+ automatic mode.
+- `f32`: always uses FP32 cache storage.
+- `f16`: always uses FP16 cache storage, including with ordinary attention.
+- `bf16`, `q4_1`, `q5_0`, `q5_1`, `q8_0`, `q4_K`, `q6_K`, `iq4_nl`, and `iq4_xs`:
+ explicitly select another supported storage type. Quantized storage is lossy;
+ `auto` never selects it. Unsupported or incompatible types are ignored with a
+ warning, keeping the previous setting or the default.
-> `This is an RGBA image with transparency. <your description>. The image has alpha channel and the background is transparent.`
+For example, add `--model-args qwen_image_2_1_prefix_cache_type=q8_0` for 8-bit
+cache storage. Smaller storage types reduce persistent cache memory but can
+change numerical results and add conversion work. Attention working buffers
+still require floating-point storage.
-Since transparency is decided by the prompt rather than by the input or an explicit switch, the same format applies equally to editing, whether or not the reference image itself has an alpha channel. Note that alpha is kept only in `.png` and `.webp` outputs; saving as `.jpg` drops the transparency.
+For the default 32-layer model and 4096 condition tokens, approximate memory per
+condition is as follows, excluding weights, working buffers, and overhead:
-Here are some examples ran with Q6_K quantization:
-| Input | Prompt | Output |
-| --- | --- | --- |
-|  | This is an RGBA image with transparency. Replace the text "BLOOM" with "Qwen Image 2.1", keeping the same font of the original text. The image has alpha channel and the background is transparent. |  |
-|  | This is an RGBA image with transparency. Remove the background of the image, keeping only the text and cat. The image has alpha channel and the background is transparent. |  |
+| Cache type | Memory |
+| --- | ---: |
+| `f32` | 4 GiB |
+| `f16` | 2 GiB |
+| `q8_0` | 1.0625 GiB |
+| `q4_0` | 0.5625 GiB |
-### Other features
+If cached execution runs out of memory, the runtime releases the caches and
+retries the full sequence without caching for the rest of that sampling run.
+Some conditioning extensions also use the full-sequence path.
-Other features of the model could be found on the [model card from QwenLM/Qwen-Image-2.1 repo](https://github.com/QwenLM/Qwen-Image-2.1), including 2 finetuned prompt rewriting Qwen3.5-9B model.
+Disable caching with `--model-args qwen_image_2_1_prefix_cache=false`. Numerical
+results can differ slightly because caching changes computation sizes. See the
+[prefix cache developer notes](../development/qwen_image_prefix_cache.md) for
+storage compatibility and implementation details.
diff --git a/docs/models/qwen_image_edit.md b/docs/models/qwen_image_edit.md
index 945e0b8..adec6ff 100644
--- a/docs/models/qwen_image_edit.md
+++ b/docs/models/qwen_image_edit.md
@@ -1,48 +1,150 @@
-# How to Use
-
-## Download weights
-
-- Download Qwen Image
- - Qwen Image Edit
- - safetensors: https://huggingface.co/Comfy-Org/Qwen-Image-Edit_ComfyUI/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/QuantStack/Qwen-Image-Edit-GGUF/tree/main
- - Qwen Image Edit 2509
- - safetensors: https://huggingface.co/Comfy-Org/Qwen-Image-Edit_ComfyUI/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/QuantStack/Qwen-Image-Edit-2509-GGUF/tree/main
- - Qwen Image Edit 2511
- - safetensors: https://huggingface.co/Comfy-Org/Qwen-Image-Edit_ComfyUI/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/unsloth/Qwen-Image-Edit-2511-GGUF/tree/main
-- Download vae
- - safetensors: https://huggingface.co/Comfy-Org/Qwen-Image_ComfyUI/tree/main/split_files/vae
-- Download qwen_2.5_vl 7b
- - safetensors: https://huggingface.co/Comfy-Org/Qwen-Image_ComfyUI/tree/main/split_files/text_encoders
- - gguf: https://huggingface.co/mradermacher/Qwen2.5-VL-7B-Instruct-GGUF/tree/main
-
-## Examples
-
-### Qwen Image Edit
+# Qwen Image Edit
+Qwen Image Edit supports reference-image editing with the original, 2509, and 2511 checkpoints.
+
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Qwen Image | Qwen Image Edit<br>[Safetensors](https://huggingface.co/Comfy-Org/Qwen-Image-Edit_ComfyUI/tree/main/split_files/diffusion_models)<br>[GGUF](https://huggingface.co/QuantStack/Qwen-Image-Edit-GGUF/tree/main)<br>Qwen Image Edit 2509<br>[Safetensors](https://huggingface.co/Comfy-Org/Qwen-Image-Edit_ComfyUI/tree/main/split_files/diffusion_models)<br>[GGUF](https://huggingface.co/QuantStack/Qwen-Image-Edit-2509-GGUF/tree/main)<br>Qwen Image Edit 2511<br>[Safetensors](https://huggingface.co/Comfy-Org/Qwen-Image-Edit_ComfyUI/tree/main/split_files/diffusion_models)<br>[GGUF](https://huggingface.co/unsloth/Qwen-Image-Edit-2511-GGUF/tree/main) | `--diffusion-model` | Required |
+| vae | [Safetensors](https://huggingface.co/Comfy-Org/Qwen-Image_ComfyUI/tree/main/split_files/vae) | `--vae` | Use matching VAE |
+| qwen_2.5_vl 7b | [Safetensors](https://huggingface.co/Comfy-Org/Qwen-Image_ComfyUI/tree/main/split_files/text_encoders)<br>[GGUF](https://huggingface.co/mradermacher/Qwen2.5-VL-7B-Instruct-GGUF/tree/main) | `--llm` | Use matching text encoder |
+
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Qwen Image Edit (`qwen-image-edit`) | `diffusion_model`, `llm`, `llm_vision`, `vae`, `tae` |
+| Qwen Image Edit 2509 (`qwen-image-edit-2509`) | `diffusion_model`, `llm`, `llm_vision`, `vae`, `tae` |
+| Qwen Image Edit 2511 (`qwen-image-edit-2511`) | `diffusion_model`, `llm`, `llm_vision`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Qwen Image Edit
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\Qwen_Image_Edit-Q8_0.gguf `
+ --vae ..\models\vae\qwen_image_vae.safetensors `
+ --llm ..\models\text_encoders\qwen_2.5_vl_7b.safetensors `
+ -r ..\inputs\flux\flux1-dev-q8_0.png `
+ -p "change 'flux.cpp' to 'edit.cpp'" `
+ --cfg-scale 2.5 `
+ --sampling-method euler `
+ --flow-shift 3 `
+ --offload-to-cpu `
+ -v `
+ --seed 1118877715456453
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\Qwen_Image_Edit-Q8_0.gguf --vae ..\models\vae\qwen_image_vae.safetensors --llm ..\models\text_encoders\qwen_2.5_vl_7b.safetensors --cfg-scale 2.5 --sampling-method euler -v --offload-to-cpu --flow-shift 3 -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'edit.cpp'" --seed 1118877715456453
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/Qwen_Image_Edit-Q8_0.gguf \
+ --vae ../models/vae/qwen_image_vae.safetensors \
+ --llm ../models/text_encoders/qwen_2.5_vl_7b.safetensors \
+ -r ../inputs/flux/flux1-dev-q8_0.png \
+ -p "change 'flux.cpp' to 'edit.cpp'" \
+ --cfg-scale 2.5 \
+ --sampling-method euler \
+ --flow-shift 3 \
+ --offload-to-cpu \
+ -v \
+ --seed 1118877715456453
```
<img alt="qwen_image_edit" src="../../assets/qwen/qwen_image_edit.png" />
+#### Qwen Image Edit 2509
-### Qwen Image Edit 2509
+**Windows (PowerShell)**
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\Qwen-Image-Edit-2509-Q4_K_S.gguf `
+ --vae ..\models\vae\qwen_image_vae.safetensors `
+ --llm ..\models\text_encoders\Qwen2.5-VL-7B-Instruct-Q8_0.gguf `
+ --llm_vision ..\models\text_encoders\Qwen2.5-VL-7B-Instruct.mmproj-Q8_0.gguf `
+ -r ..\inputs\flux\flux1-dev-q8_0.png `
+ -p "change 'flux.cpp' to 'Qwen Image Edit 2509'" `
+ --cfg-scale 2.5 `
+ --sampling-method euler `
+ --flow-shift 3 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\Qwen-Image-Edit-2509-Q4_K_S.gguf --vae ..\models\vae\qwen_image_vae.safetensors --llm ..\models\text_encoders\Qwen2.5-VL-7B-Instruct-Q8_0.gguf --llm_vision ..\models\text_encoders\Qwen2.5-VL-7B-Instruct.mmproj-Q8_0.gguf --cfg-scale 2.5 --sampling-method euler -v --offload-to-cpu --flow-shift 3 -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'Qwen Image Edit 2509'"
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/Qwen-Image-Edit-2509-Q4_K_S.gguf \
+ --vae ../models/vae/qwen_image_vae.safetensors \
+ --llm ../models/text_encoders/Qwen2.5-VL-7B-Instruct-Q8_0.gguf \
+ --llm_vision ../models/text_encoders/Qwen2.5-VL-7B-Instruct.mmproj-Q8_0.gguf \
+ -r ../inputs/flux/flux1-dev-q8_0.png \
+ -p "change 'flux.cpp' to 'Qwen Image Edit 2509'" \
+ --cfg-scale 2.5 \
+ --sampling-method euler \
+ --flow-shift 3 \
+ --offload-to-cpu \
+ -v
```
<img alt="qwen_image_edit_2509" src="../../assets/qwen/qwen_image_edit_2509.png" />
-### Qwen Image Edit 2511
+#### Qwen Image Edit 2511
To use the new Qwen Image Edit 2511 mode, `--model-args qwen_image_zero_cond_t=true` must be enabled; otherwise, image editing quality will degrade significantly.
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\qwen-image-edit-2511-Q4_K_M.gguf `
+ --vae ..\models\vae\qwen_image_vae.safetensors `
+ --llm ..\models\text_encoders\qwen_2.5_vl_7b.safetensors `
+ --model-args qwen_image_zero_cond_t=true `
+ -r ..\inputs\flux\flux1-dev-q8_0.png `
+ -p "change 'flux.cpp' to 'edit.cpp'" `
+ --cfg-scale 2.5 `
+ --sampling-method euler `
+ --flow-shift 3 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\qwen-image-edit-2511-Q4_K_M.gguf --vae ..\models\vae\qwen_image_vae.safetensors --llm ..\models\text_encoders\qwen_2.5_vl_7b.safetensors --cfg-scale 2.5 --sampling-method euler -v --offload-to-cpu --flow-shift 3 -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'edit.cpp'" --model-args qwen_image_zero_cond_t=true
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/qwen-image-edit-2511-Q4_K_M.gguf \
+ --vae ../models/vae/qwen_image_vae.safetensors \
+ --llm ../models/text_encoders/qwen_2.5_vl_7b.safetensors \
+ --model-args qwen_image_zero_cond_t=true \
+ -r ../inputs/flux/flux1-dev-q8_0.png \
+ -p "change 'flux.cpp' to 'edit.cpp'" \
+ --cfg-scale 2.5 \
+ --sampling-method euler \
+ --flow-shift 3 \
+ --offload-to-cpu \
+ -v
```
<img alt="qwen_image_edit_2509" src="../../assets/qwen/qwen_image_edit_2511.png" />
diff --git a/docs/models/relay_vsr.md b/docs/models/relay_vsr.md
index 5485d42..4900fa4 100644
--- a/docs/models/relay_vsr.md
+++ b/docs/models/relay_vsr.md
@@ -1,9 +1,14 @@
-# RelayVSR image and video super-resolution
+# RelayVSR
[RelayVSR](https://github.com/kopperx/RelayVSR) upscales images and videos by
2x or 4x with `-M vid_upscale`.
-## Weights
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| RelayVSR diffusion model | [ComfyUI RelayVSR](https://huggingface.co/Comfy-Org/RelayVSR) | `--diffusion-model` | Match the requested 2x or 4x scale |
+| RelayVSR VAE | Matching scale-specific VAE from the same repository | `--vae` | Required; ordinary Wan VAE is incompatible |
[ComfyUI safetensors weights](https://huggingface.co/Comfy-Org/RelayVSR) load
directly. Select the matching pair for the requested scale:
@@ -17,14 +22,40 @@ No separate text encoder or ordinary Wan VAE is needed.
## Usage
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### CLI
+
For a video, extract numbered frames into a directory, then run:
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_upscale `
+ --diffusion-model ..\models\diffusion_models\relayvsr_x2_lightx2v_int8_convrot.safetensors `
+ --vae ..\models\vae\relayvsr_flash_vae_x2_fp32.safetensors `
+ --input-frames input_frames `
+ --upscale-factor 2 `
+ --fps 24 `
+ --vsr-window-size 16 `
+ -s 42 `
+ -o output.avi
+```
+
+**Linux/macOS**
+
```sh
-sd-cli -M vid_upscale \
- --diffusion-model models/diffusion_models/relayvsr_x2_lightx2v_int8_convrot.safetensors \
- --vae models/vae/relayvsr_flash_vae_x2_fp32.safetensors \
- --input-frames input_frames --upscale-factor 2 --fps 24 \
- --vsr-window-size 16 -s 42 -o output.avi
+./bin/sd-cli \
+ -M vid_upscale \
+ --diffusion-model ../models/diffusion_models/relayvsr_x2_lightx2v_int8_convrot.safetensors \
+ --vae ../models/vae/relayvsr_flash_vae_x2_fp32.safetensors \
+ --input-frames input_frames \
+ --upscale-factor 2 \
+ --fps 24 \
+ --vsr-window-size 16 \
+ -s 42 \
+ -o output.avi
```
Frames are read in filename order. Set `--fps` to the source video's frame rate.
@@ -35,7 +66,7 @@ For a single image, replace `--input-frames input_frames` with `-i input.png`
and use `-o output.png` (or JPEG/WebP). No FPS setting is needed for an image.
`-i` / `--init-img` and `--input-frames` are mutually exclusive.
-## Settings and limits
+## Notes and limitations
- `--upscale-factor` is required. Use 2 or 4 with the corresponding weights.
Output width and height are exactly the input dimensions times the scale.
diff --git a/docs/models/sd.md b/docs/models/sd.md
index 746d52e..2d1ab53 100644
--- a/docs/models/sd.md
+++ b/docs/models/sd.md
@@ -1,37 +1,138 @@
-## Download weights
+# Stable Diffusion 1.x, 2.x, and SDXL
-- download original weights(.ckpt or .safetensors). For example
- - Stable Diffusion v1.4 from https://huggingface.co/CompVis/stable-diffusion-v-1-4-original
- - Stable Diffusion v1.5 from https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5
- - Stable Diffusion v2.1 from https://huggingface.co/Manojb/stable-diffusion-2-1-base
- - Stable Diffusion 3 2B from https://huggingface.co/stabilityai/stable-diffusion-3-medium
+Stable Diffusion 1.x, 2.x, and SDXL support text-to-image and image-to-image
+generation from single-file checkpoints.
-### txt2img example
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| SD 1.4 checkpoint | [CompVis SD 1.4](https://huggingface.co/CompVis/stable-diffusion-v-1-4-original) | `-m` / `--model` | Choose a matching SD checkpoint |
+| SD 1.5 checkpoint | [Stable Diffusion 1.5](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5) | `-m` / `--model` | Choose a matching SD checkpoint |
+| SD 2.1 checkpoint | [Stable Diffusion 2.1](https://huggingface.co/Manojb/stable-diffusion-2-1-base) | `-m` / `--model` | Choose a matching SD checkpoint |
+| SDXL checkpoint | `sd_xl_base_1.0.safetensors` from [SDXL](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0) | `-m` / `--model` | For SDXL examples |
+| SDXL VAE | [`sdxl_vae-fp16-fix.safetensors`](https://huggingface.co/madebyollin/sdxl-vae-fp16-fix) | `--vae` | Use an override when required by the checkpoint |
+
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| SD 1.x (`sd1-checkpoint`) | `model`, `vae`, `tae` |
+| SD 2.1 512 (`sd2-512-checkpoint`) | `model`, `vae`, `tae` |
+| SD 2.1 768 (`sd2-768-checkpoint`) | `model`, `vae`, `tae` |
+| SDXL (`sdxl-checkpoint`) | `model`, `vae`, `tae` |
+| SD Turbo (`sd-turbo`) | `model`, `vae`, `tae` |
+| SDXL Turbo (`sdxl-turbo`) | `model`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### SD 1.4
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe -m ..\models\checkpoints\sd-v1-4.ckpt -p "a lovely cat"
+```
+
+**Linux/macOS**
```sh
-./bin/sd-cli -m ../models/sd-v1-4.ckpt -p "a lovely cat"
-# ./bin/sd-cli -m ../models/v1-5-pruned-emaonly.safetensors -p "a lovely cat"
-# ./bin/sd-cli -m ../models/sd_xl_base_1.0.safetensors --vae ../models/sdxl_vae-fp16-fix.safetensors -H 1024 -W 1024 -p "a lovely cat" -v
-# ./bin/sd-cli -m ../models/sd3_medium_incl_clips_t5xxlfp16.safetensors -H 1024 -W 1024 -p 'a lovely cat holding a sign says \"Stable Diffusion CPP\"' --cfg-scale 4.5 --sampling-method euler -v --clip-on-cpu
-# ./bin/sd-cli --diffusion-model ../models/flux1-dev-q3_k.gguf --vae ../models/ae.sft --clip_l ../models/clip_l.safetensors --t5xxl ../models/t5xxl_fp16.safetensors -p "a lovely cat holding a sign says 'flux.cpp'" --cfg-scale 1.0 --sampling-method euler -v --clip-on-cpu
-# ./bin/sd-cli -m ..\models\sd3.5_large.safetensors --clip_l ..\models\clip_l.safetensors --clip_g ..\models\clip_g.safetensors --t5xxl ..\models\t5xxl_fp16.safetensors -H 1024 -W 1024 -p 'a lovely cat holding a sign says \"Stable diffusion 3.5 Large\"' --cfg-scale 4.5 --sampling-method euler -v --clip-on-cpu
+./bin/sd-cli -m ../models/checkpoints/sd-v1-4.ckpt -p "a lovely cat"
```
-Using formats of different precisions will yield results of varying quality.
+#### SD 1.5
-| f32 | f16 |q8_0 |q5_0 |q5_1 |q4_0 |q4_1 |
-| ---- |---- |---- |---- |---- |---- |---- |
-|  | | | | | | |
+**Windows (PowerShell)**
-### img2img example
+```powershell
+.\bin\Release\sd-cli.exe -m ..\models\checkpoints\v1-5-pruned-emaonly.safetensors -p "a lovely cat"
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli -m ../models/checkpoints/v1-5-pruned-emaonly.safetensors -p "a lovely cat"
+```
-- `./output.png` is the image generated from the above txt2img pipeline
+#### SDXL
+**Windows (PowerShell)**
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\sd_xl_base_1.0.safetensors `
+ --vae ..\models\vae\sdxl_vae-fp16-fix.safetensors `
+ -p "a lovely cat" `
+ -H 1024 `
+ -W 1024 `
+ -v
```
-./bin/sd-cli -m ../models/sd-v1-4.ckpt -p "cat with blue eyes" -i ./output.png -o ./img2img_output.png --strength 0.4
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -m ../models/checkpoints/sd_xl_base_1.0.safetensors \
+ --vae ../models/vae/sdxl_vae-fp16-fix.safetensors \
+ -p "a lovely cat" \
+ -H 1024 \
+ -W 1024 \
+ -v
+```
+
+#### img2img example
+
+Use the image generated above as `./output.png`.
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\sd-v1-4.ckpt `
+ -p "cat with blue eyes" `
+ -i .\output.png `
+ --strength 0.4 `
+ -o .\img2img_output.png
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -m ../models/checkpoints/sd-v1-4.ckpt \
+ -p "cat with blue eyes" \
+ -i ./output.png \
+ --strength 0.4 \
+ -o ./img2img_output.png
```
<p align="center">
<img src="../../assets/img2img_output.png" width="256x">
</p>
+
+#### Precision comparison
+
+Using formats of different precisions will yield results of varying quality.
+
+| f32 | f16 |q8_0 |q5_0 |q5_1 |q4_0 |q4_1 |
+| ---- |---- |---- |---- |---- |---- |---- |
+|  | | | | | | |
+
+## Notes and limitations
+
+See [SD3 / SD3.5](sd3.md) for Stable Diffusion 3, and [FLUX.1](flux.md) for FLUX.
+The [SD3 model repository](https://huggingface.co/stabilityai/stable-diffusion-3-medium) uses a different component setup.
+For distilled and tiny variants, see [distilled SD models](distilled_sd.md).
diff --git a/docs/models/sd3.md b/docs/models/sd3.md
index 932406b..12cab00 100644
--- a/docs/models/sd3.md
+++ b/docs/models/sd3.md
@@ -1,20 +1,75 @@
-# How to Use
+# Stable Diffusion 3 / 3.5
-## Download weights
+Stable Diffusion 3 and 3.5 generate images from text. The example below uses SD3.5 Large with separate text encoders.
-- Download sd3.5_large from https://huggingface.co/stabilityai/stable-diffusion-3.5-large/blob/main/sd3.5_large.safetensors
-- Download clip_g from https://huggingface.co/Comfy-Org/stable-diffusion-3.5-fp8/blob/main/text_encoders/clip_g.safetensors
-- Download clip_l from https://huggingface.co/Comfy-Org/stable-diffusion-3.5-fp8/blob/main/text_encoders/clip_l.safetensors
-- Download t5xxl from https://huggingface.co/Comfy-Org/stable-diffusion-3.5-fp8/blob/main/text_encoders/t5xxl_fp16.safetensors
+## Model files
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| sd3.5_large | sd3.5_large from [Download](https://huggingface.co/stabilityai/stable-diffusion-3.5-large/blob/main/sd3.5_large.safetensors) | `--model` | Required |
+| clip_g | clip_g from [Download](https://huggingface.co/Comfy-Org/stable-diffusion-3.5-fp8/blob/main/text_encoders/clip_g.safetensors) | `--clip_g` | Required |
+| clip_l | clip_l from [Download](https://huggingface.co/Comfy-Org/stable-diffusion-3.5-fp8/blob/main/text_encoders/clip_l.safetensors) | `--clip_l` | Required |
+| t5xxl | t5xxl from [Download](https://huggingface.co/Comfy-Org/stable-diffusion-3.5-fp8/blob/main/text_encoders/t5xxl_fp16.safetensors) | `--t5xxl` | Required |
-## Run
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| SD 3 Medium (`sd3-medium`) | `model`, `vae`, `tae` |
+| SD 3.5 Medium (`sd35-medium`) | `model`, `clip_l`, `clip_g`, `t5xxl`, `vae`, `tae` |
+| SD 3.5 Large (`sd35-large`) | `model`, `clip_l`, `clip_g`, `t5xxl`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### SD3.5 Large
-### SD3.5 Large
For example:
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\sd3.5_large.safetensors `
+ --clip_l ..\models\text_encoders\clip_l.safetensors `
+ --clip_g ..\models\text_encoders\clip_g.safetensors `
+ --t5xxl ..\models\text_encoders\t5xxl_fp16.safetensors `
+ -p "a lovely cat holding a sign says \`"Stable diffusion 3.5 Large\`"" `
+ --cfg-scale 4.5 `
+ --sampling-method euler `
+ -H 1024 `
+ -W 1024 `
+ --clip-on-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe -m ..\models\sd3.5_large.safetensors --clip_l ..\models\clip_l.safetensors --clip_g ..\models\clip_g.safetensors --t5xxl ..\models\t5xxl_fp16.safetensors -H 1024 -W 1024 -p 'a lovely cat holding a sign says \"Stable diffusion 3.5 Large\"' --cfg-scale 4.5 --sampling-method euler -v --clip-on-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -m ../models/checkpoints/sd3.5_large.safetensors \
+ --clip_l ../models/text_encoders/clip_l.safetensors \
+ --clip_g ../models/text_encoders/clip_g.safetensors \
+ --t5xxl ../models/text_encoders/t5xxl_fp16.safetensors \
+ -p "a lovely cat holding a sign says \\\"Stable diffusion 3.5 Large\\\"" \
+ --cfg-scale 4.5 \
+ --sampling-method euler \
+ -H 1024 \
+ -W 1024 \
+ --clip-on-cpu \
+ -v
```
-
\ No newline at end of file
+
diff --git a/docs/models/seedvr2.md b/docs/models/seedvr2.md
index b5b4b1b..0a48914 100644
--- a/docs/models/seedvr2.md
+++ b/docs/models/seedvr2.md
@@ -1,8 +1,13 @@
-# SeedVR2 image and video super-resolution
+# SeedVR2
SeedVR2 upscales images and videos with `-M vid_upscale`. Support is experimental.
-## Weights
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Diffusion model | [ComfyUI SeedVR2](https://huggingface.co/Comfy-Org/SeedVR2) | `--diffusion-model` | Choose 3B or 7B Sharp below |
+| SeedVR2 VAE | `seedvr2_ema_vae_fp16.safetensors` from the same repository | `--vae` | Required; shared by both variants |
These [ComfyUI safetensors weights](https://huggingface.co/Comfy-Org/SeedVR2)
load directly, without conversion or a separate text encoder:
@@ -14,30 +19,79 @@ load directly, without conversion or a separate text encoder:
Use the matching SeedVR2 VAE for either model. The 7B model requires more memory.
-## Upscale an image
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### CLI
+
+#### Upscale an image
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_upscale `
+ --diffusion-model ..\models\diffusion_models\seedvr2_3b_int8_convrot.safetensors `
+ --vae ..\models\vae\seedvr2_ema_vae_fp16.safetensors `
+ -i input.png `
+ --upscale-factor 2 `
+ -s 42 `
+ -o restored.png
+```
+
+**Linux/macOS**
```sh
-sd-cli -M vid_upscale \
- --diffusion-model models/diffusion_models/seedvr2_3b_int8_convrot.safetensors \
- --vae models/vae/seedvr2_ema_vae_fp16.safetensors \
- -i input.png --upscale-factor 2 -s 42 -o restored.png
+./bin/sd-cli \
+ -M vid_upscale \
+ --diffusion-model ../models/diffusion_models/seedvr2_3b_int8_convrot.safetensors \
+ --vae ../models/vae/seedvr2_ema_vae_fp16.safetensors \
+ -i input.png \
+ --upscale-factor 2 \
+ -s 42 \
+ -o restored.png
```
`-i` / `--init-img` accepts a single image. Outputs can be PNG, JPEG, or WebP.
No FPS or temporal chunk setting is needed for an image.
-## Upscale a video
+#### Upscale a video
Extract the video into numbered frames, then pass the frame directory:
+**Windows (PowerShell)**
+
+```powershell
+mkdir frames
+ffmpeg -i input.mp4 -fps_mode passthrough frames\%06d.png
+.\bin\Release\sd-cli.exe `
+ -M vid_upscale `
+ --diffusion-model ..\models\diffusion_models\seedvr2_3b_int8_convrot.safetensors `
+ --vae ..\models\vae\seedvr2_ema_vae_fp16.safetensors `
+ --input-frames frames `
+ --upscale-factor 2 `
+ --fps 24 `
+ --vsr-temporal-chunk-size 1 `
+ -s 42 `
+ -o restored.avi
+```
+
+**Linux/macOS**
+
```sh
mkdir frames
ffmpeg -i input.mp4 -fps_mode passthrough frames/%06d.png
-sd-cli -M vid_upscale \
- --diffusion-model models/diffusion_models/seedvr2_3b_int8_convrot.safetensors \
- --vae models/vae/seedvr2_ema_vae_fp16.safetensors \
- --input-frames frames --upscale-factor 2 --fps 24 \
- --vsr-temporal-chunk-size 1 -s 42 -o restored.avi
+./bin/sd-cli \
+ -M vid_upscale \
+ --diffusion-model ../models/diffusion_models/seedvr2_3b_int8_convrot.safetensors \
+ --vae ../models/vae/seedvr2_ema_vae_fp16.safetensors \
+ --input-frames frames \
+ --upscale-factor 2 \
+ --fps 24 \
+ --vsr-temporal-chunk-size 1 \
+ -s 42 \
+ -o restored.avi
```
Set `--fps` to the source video's frame rate; 24 is only the example above.
@@ -46,7 +100,7 @@ Frames are read in filename order. Use either `-i` or `--input-frames`, not both
Video outputs support AVI, WebM, and animated WebP. To save individual frames,
use an output pattern such as `-o restored/%06d.png`.
-## Settings and limits
+## Notes and limitations
- `--upscale-factor` is required and must be a positive integer. Output width
and height are exactly the input dimensions multiplied by this value.
diff --git a/docs/models/sefi_image.md b/docs/models/sefi_image.md
index f588da8..1d6ffbd 100644
--- a/docs/models/sefi_image.md
+++ b/docs/models/sefi_image.md
@@ -1,8 +1,14 @@
-# How to Use
+# SeFi-Image
SeFi-Image uses a Flux2-style dual-time transformer (semantic + texture streams), the standard Flux2 VAE, and Qwen3-VL as the LLM text encoder. Tech report: [arXiv:2606.22568](https://arxiv.org/abs/2606.22568).
-## Download weights
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| SeFi transformer | [SeFi-Image repositories](https://huggingface.co/SeFi-Image) | `--diffusion-model` | Choose matching scale and family; prepare as described below |
+| Qwen3-VL text encoder | 2B for SeFi 1B/2B; 4B for SeFi 5B | `--llm` | Required; convert as described below |
+| FLUX.2 VAE | [FLUX.2 dev](https://huggingface.co/black-forest-labs/FLUX.2-dev) | `--vae` | Required; `flux2_ae.safetensors` |
The SeFi-Image family ships in three scales (1B / 2B / 5B) and three families (Base / RL / turbo), all gated on Hugging Face under https://huggingface.co/SeFi-Image.
@@ -10,41 +16,163 @@ The SeFi-Image family ships in three scales (1B / 2B / 5B) and three families (B
- 5B variants pair with Qwen3-VL-4B-Instruct.
- All variants use the standard Flux2 VAE (`flux2_ae.safetensors` from https://huggingface.co/black-forest-labs/FLUX.2-dev).
-Convert the transformer and text encoder to sd.cpp safetensors:
+Prepare the transformer and text encoder from the source repository root, using the conversion scripts:
+
+**Windows (PowerShell)**
-```bash
-python3 scripts/convert_sefi.py <hf_repo_dir> <out_dir>/sefi_<scale>_<family>.safetensors
-python3 scripts/convert_qwen3_vl.py <hf_repo_dir>/Qwen3-VL-XB-Instruct <out_dir>/qwen3_vl_<X>b.safetensors
+```powershell
+python scripts\convert_sefi.py "<hf_repo_dir>" "<out_dir>/sefi_<scale>_<family>.safetensors"
+python scripts\convert_qwen3_vl.py "<hf_repo_dir>/Qwen3-VL-XB-Instruct" "<out_dir>/qwen3_vl_<X>b.safetensors"
```
-## Variant defaults
+**Linux/macOS**
-| Family | timestep_shift_alpha | steps | cfg-scale |
-|---|---|---|---|
-| Base | 0.3 | 50 | 4.0 |
-| RL | 0.3 | 50 | 4.0 |
-| turbo | 1.0 | 4 | 1.0 |
+```sh
+python3 scripts/convert_sefi.py "<hf_repo_dir>" "<out_dir>/sefi_<scale>_<family>.safetensors"
+python3 scripts/convert_qwen3_vl.py "<hf_repo_dir>/Qwen3-VL-XB-Instruct" "<out_dir>/qwen3_vl_<X>b.safetensors"
+```
-The dispatcher picks `alpha` from the filename (`turbo` substring => 1.0, otherwise 0.3). Override via `--extra-sample-args sefi_alpha=<value>` or `sefi_delta_t=<value>`.
+## Usage
-## Examples
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
-### 1B / 2B turbo
+### Web UI
-```
-./build/bin/sd-cli --diffusion-model /path/to/sefi_1b_turbo.safetensors --vae /path/to/flux2_ae.safetensors --llm /path/to/qwen3_vl_2b.safetensors -p "a photograph of an orange tabby cat sitting on a couch" --cfg-scale 1.0 --steps 4 -W 1024 -H 1024 -s 42 --offload-to-cpu -o out.png
-```
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| SeFi Image 5B RL (`sefi-image`) | `diffusion_model`, `llm`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### 1B / 2B turbo
-### 1B / 2B base
+**Windows (PowerShell)**
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\sefi_1b_turbo.safetensors `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ --llm ..\models\text_encoders\qwen3_vl_2b.safetensors `
+ -p "a photograph of an orange tabby cat sitting on a couch" `
+ --cfg-scale 1.0 `
+ --steps 4 `
+ -W 1024 `
+ -H 1024 `
+ --offload-to-cpu `
+ -s 42 `
+ -o out.png
```
-./build/bin/sd-cli --diffusion-model /path/to/sefi_1b_base.safetensors --vae /path/to/flux2_ae.safetensors --llm /path/to/qwen3_vl_2b.safetensors -p "a photograph of an orange tabby cat sitting on a couch" --cfg-scale 4.0 --steps 50 -W 1024 -H 1024 -s 42 --offload-to-cpu -o out.png
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/sefi_1b_turbo.safetensors \
+ --vae ../models/vae/flux2_ae.safetensors \
+ --llm ../models/text_encoders/qwen3_vl_2b.safetensors \
+ -p "a photograph of an orange tabby cat sitting on a couch" \
+ --cfg-scale 1.0 \
+ --steps 4 \
+ -W 1024 \
+ -H 1024 \
+ --offload-to-cpu \
+ -s 42 \
+ -o out.png
+```
+
+#### 1B / 2B base
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\sefi_1b_base.safetensors `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ --llm ..\models\text_encoders\qwen3_vl_2b.safetensors `
+ -p "a photograph of an orange tabby cat sitting on a couch" `
+ --cfg-scale 4.0 `
+ --steps 50 `
+ -W 1024 `
+ -H 1024 `
+ --offload-to-cpu `
+ -s 42 `
+ -o out.png
```
-### 5B (needs streaming on 12 GiB VRAM)
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/sefi_1b_base.safetensors \
+ --vae ../models/vae/flux2_ae.safetensors \
+ --llm ../models/text_encoders/qwen3_vl_2b.safetensors \
+ -p "a photograph of an orange tabby cat sitting on a couch" \
+ --cfg-scale 4.0 \
+ --steps 50 \
+ -W 1024 \
+ -H 1024 \
+ --offload-to-cpu \
+ -s 42 \
+ -o out.png
+```
+#### 5B (needs streaming on 12 GiB VRAM)
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\sefi_5b_turbo.safetensors `
+ --vae ..\models\vae\flux2_ae.safetensors `
+ --llm ..\models\text_encoders\qwen3_vl_4b.safetensors `
+ -p "a photograph of an orange tabby cat sitting on a couch" `
+ --cfg-scale 1.0 `
+ --steps 4 `
+ -W 1024 `
+ -H 1024 `
+ --max-vram 8 `
+ --offload-to-cpu `
+ -s 42 `
+ -o out.png
```
-./build/bin/sd-cli --diffusion-model /path/to/sefi_5b_turbo.safetensors --vae /path/to/flux2_ae.safetensors --llm /path/to/qwen3_vl_4b.safetensors -p "a photograph of an orange tabby cat sitting on a couch" --cfg-scale 1.0 --steps 4 -W 1024 -H 1024 -s 42 --max-vram 8 --offload-to-cpu -o out.png
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/sefi_5b_turbo.safetensors \
+ --vae ../models/vae/flux2_ae.safetensors \
+ --llm ../models/text_encoders/qwen3_vl_4b.safetensors \
+ -p "a photograph of an orange tabby cat sitting on a couch" \
+ --cfg-scale 1.0 \
+ --steps 4 \
+ -W 1024 \
+ -H 1024 \
+ --max-vram 8 \
+ --offload-to-cpu \
+ -s 42 \
+ -o out.png
```
<img alt="SeFi-Image 5B turbo example" src="../../assets/sefi_image/example.png" />
+
+## Options
+
+### Variant defaults
+
+| Family | timestep_shift_alpha | steps | cfg-scale |
+|---|---|---|---|
+| Base | 0.3 | 50 | 4.0 |
+| RL | 0.3 | 50 | 4.0 |
+| turbo | 1.0 | 4 | 1.0 |
+
+The dispatcher picks `alpha` from the filename (`turbo` substring => 1.0, otherwise 0.3). Override via `--extra-sample-args sefi_alpha=<value>` or `sefi_delta_t=<value>`.
diff --git a/docs/models/sensenova_u1.md b/docs/models/sensenova_u1.md
index 57b22a4..e77ab39 100644
--- a/docs/models/sensenova_u1.md
+++ b/docs/models/sensenova_u1.md
@@ -1,37 +1,69 @@
-# How to Use
+# SenseNova U1.5
SenseNova U1.5 is an 8B MoT model that performs diffusion directly in RGB pixel
space. It does not require a separate text encoder or VAE.
-## Download weights
+## Model files
-- Download SenseNova U1.5 8B MoT
- - safetensors: https://huggingface.co/sensenova/SenseNova-U1.5-8B-MoT
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| SenseNova U1.5 8B MoT | [Safetensors](https://huggingface.co/sensenova/SenseNova-U1.5-8B-MoT) | `--model` | Required |
Pass the complete downloaded repository directory to `--model`. The directory
must contain `model.safetensors.index.json`, every referenced Safetensors shard,
and the tokenizer files.
-## Examples
+## Usage
-### CUDA
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
-```bash
+### Web UI
+
+Follow the server instructions for
+[sharded checkpoints](../../examples/server/README.md#sharded-checkpoints).
+Pass the complete repository directory with `--model` when starting the server,
+using the same model path as the CLI examples below. The browser then uses
+**Command-line model (all features)** for that loaded checkpoint.
+
+### CLI
+
+#### CUDA
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --model ..\models\checkpoints\SenseNova-U1.5-8B-MoT `
+ --prompt "a red cube on a white background" `
+ --steps 50 `
+ --cfg-scale 4 `
+ --flow-shift 3 `
+ --sampling-method euler `
+ --width 2048 `
+ --height 2048 `
+ --rng cuda `
+ --seed 42 `
+ --output output.png
+```
+
+**Linux/macOS**
+
+```sh
./bin/sd-cli \
- --model /path/to/SenseNova-U1.5-8B-MoT \
+ --model ../models/checkpoints/SenseNova-U1.5-8B-MoT \
--prompt "a red cube on a white background" \
- --width 2048 \
- --height 2048 \
--steps 50 \
--cfg-scale 4 \
--flow-shift 3 \
- --seed 42 \
--sampling-method euler \
+ --width 2048 \
+ --height 2048 \
--rng cuda \
+ --seed 42 \
--output output.png
```
-## Notes
+## Notes and limitations
- To match the official non-thinking text-to-image pipeline, use 50 Euler
steps, CFG 4, flow shift 3, seed 42, CUDA RNG, and an empty negative prompt.
diff --git a/docs/models/taesd.md b/docs/models/taesd.md
index 8331f44..607c0b4 100644
--- a/docs/models/taesd.md
+++ b/docs/models/taesd.md
@@ -1,53 +1,130 @@
-## Using TAESD to faster decoding
+# TAESD and related tiny autoencoders
-You can use TAESD to accelerate the decoding of latent images by following these steps:
+Tiny autoencoders provide an alternative to full VAE encoding, decoding, or
+previews. Choose the file matching the base model.
-- Download the model [weights](https://huggingface.co/madebyollin/taesd/blob/main/diffusion_pytorch_model.safetensors).
+## Model files
-Or curl
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| TAESD | [Safetensors weights](https://huggingface.co/madebyollin/taesd/blob/main/diffusion_pytorch_model.safetensors) | `--taesd` / `--tae` | For compatible SD 1.x models |
+| TAEHV for Wan 2.1 | [taew2_1.safetensors](https://github.com/madebyollin/taehv/blob/main/safetensors/taew2_1.safetensors) | `--taesd` / `--tae` | Qwen Image, Wan 2.1, and Wan 2.2 A14B |
+| TAEHV for Wan 2.2 5B | [taew2_2.safetensors](https://github.com/madebyollin/taehv/blob/main/safetensors/taew2_2.safetensors) | `--taesd` / `--tae` | Wan 2.2 TI2V 5B only |
+| TAEQI2.1 | [taeqi2_1.safetensors](https://huggingface.co/madebyollin/taeqi2_1/blob/main/taeqi2_1.safetensors) | `--taesd` / `--tae` | Qwen Image 2.1, including RGBA |
-```bash
-curl -L -O https://huggingface.co/madebyollin/taesd/resolve/main/diffusion_pytorch_model.safetensors
+### Qwen-Image and wan (TAEHV)
+
+[TAEHV](https://github.com/madebyollin/taehv) provides tiny autoencoders for the
+model families in the table. Replace `--vae PATH` with `--taesd PATH` using the
+matching file. A tiny autoencoder can reduce VAE memory requirements, with a
+possible quality tradeoff.
+
+### Qwen Image 2.1 (TAEQI2.1)
+
+[TAEQI2.1](https://github.com/madebyollin/taesd) supports Qwen Image 2.1 RGBA
+images. Download the official file directly; conversion is unnecessary. Replace
+`--vae PATH` with `--taesd taeqi2_1.safetensors` in the
+[Qwen Image 2.1 examples](qwen_image_2.1.md).
+
+### Download commands
+
+Save the files under the repository's `models/vae/` directory. From the build
+directory, create it if needed:
+
+**Windows (PowerShell)**
+
+```powershell
+New-Item -ItemType Directory -Force ..\models\vae | Out-Null
```
-- Specify the model path using the `--taesd PATH` parameter. example:
+**Linux/macOS**
-```bash
-sd-cli -m ../models/v1-5-pruned-emaonly.safetensors -p "a lovely cat" --taesd ../models/diffusion_pytorch_model.safetensors
+```sh
+mkdir -p ../models/vae
```
-### Qwen-Image and wan (TAEHV)
+**Windows (PowerShell)**
-sd.cpp also supports [TAEHV](https://github.com/madebyollin/taehv) (#937), which can be used for Qwen-Image and wan.
+```powershell
+curl.exe -L -o ..\models\vae\diffusion_pytorch_model.safetensors https://huggingface.co/madebyollin/taesd/resolve/main/diffusion_pytorch_model.safetensors
+```
-- For **Qwen-Image and wan2.1 and wan2.2-A14B**, download the wan2.1 tae [safetensors weights](https://github.com/madebyollin/taehv/blob/main/safetensors/taew2_1.safetensors)
-
- Or curl
-
- ```bash
- curl -L -O https://github.com/madebyollin/taehv/raw/refs/heads/main/safetensors/taew2_1.safetensors
- ```
+**Linux/macOS**
-- For **wan2.2-TI2V-5B**, use the wan2.2 tae [safetensors weights](https://github.com/madebyollin/taehv/blob/main/safetensors/taew2_2.safetensors)
-
- Or curl
-
- ```bash
- curl -L -O https://github.com/madebyollin/taehv/raw/refs/heads/main/safetensors/taew2_2.safetensors
- ```
+```sh
+curl -L -o ../models/vae/diffusion_pytorch_model.safetensors https://huggingface.co/madebyollin/taesd/resolve/main/diffusion_pytorch_model.safetensors
+```
-Then simply replace the `--vae xxx.safetensors` with `--tae xxx.safetensors` in the commands. If it still out of VRAM, add `--vae-conv-direct` to your command though might be slower.
+**Windows (PowerShell)**
-### Qwen Image 2.1 (TAEQI2.1)
+```powershell
+curl.exe -L -o ..\models\vae\taew2_1.safetensors https://github.com/madebyollin/taehv/raw/refs/heads/main/safetensors/taew2_1.safetensors
+```
+
+**Linux/macOS**
-For Qwen Image 2.1, use [taeqi2_1](https://github.com/madebyollin/taesd), which supports 64-channel latents, 16x spatial scaling, and RGBA images.
+```sh
+curl -L -o ../models/vae/taew2_1.safetensors https://github.com/madebyollin/taehv/raw/refs/heads/main/safetensors/taew2_1.safetensors
+```
+
+**Windows (PowerShell)**
+
+```powershell
+curl.exe -L -o ..\models\vae\taew2_2.safetensors https://github.com/madebyollin/taehv/raw/refs/heads/main/safetensors/taew2_2.safetensors
+```
-Download the official [safetensors weights](https://huggingface.co/madebyollin/taeqi2_1/blob/main/taeqi2_1.safetensors) directly; no conversion is needed:
+**Linux/macOS**
-```bash
-curl -L -o taeqi2_1.safetensors https://huggingface.co/madebyollin/taeqi2_1/resolve/main/taeqi2_1.safetensors
+```sh
+curl -L -o ../models/vae/taew2_2.safetensors https://github.com/madebyollin/taehv/raw/refs/heads/main/safetensors/taew2_2.safetensors
```
-Replace `--vae PATH` with `--taesd taeqi2_1.safetensors` in the [Qwen Image 2.1 examples](qwen_image_2.1.md) to use it for encoding and decoding. For previews only, keep `--vae PATH` and add `--taesd taeqi2_1.safetensors --taesd-preview-only --preview tae`.
+**Windows (PowerShell)**
+
+```powershell
+curl.exe -L -o ..\models\vae\taeqi2_1.safetensors https://huggingface.co/madebyollin/taeqi2_1/resolve/main/taeqi2_1.safetensors
+```
+
+**Linux/macOS**
+
+```sh
+curl -L -o ../models/vae/taeqi2_1.safetensors https://huggingface.co/madebyollin/taeqi2_1/resolve/main/taeqi2_1.safetensors
+```
+
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Use a compatible base model recipe that offers the `tae` slot, and select the
+tiny autoencoder matching that model. See [Web UI guide](../../examples/server/README.md#web-ui).
+
+### CLI
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -m ..\models\checkpoints\v1-5-pruned-emaonly.safetensors `
+ --taesd ..\models\vae\diffusion_pytorch_model.safetensors `
+ -p "a lovely cat"
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -m ../models/checkpoints/v1-5-pruned-emaonly.safetensors \
+ --taesd ../models/vae/diffusion_pytorch_model.safetensors \
+ -p "a lovely cat"
+```
+
+## Options
+
+For previews only, keep the full `--vae PATH` and add
+`--taesd PATH --taesd-preview-only --preview tae`.
-`sd-server` accepts the same `--taesd` and `--taesd-preview-only` options; the preview method is selected per request instead of via `--preview`.
+`sd-server` accepts `--taesd` and `--taesd-preview-only` at startup; choose the
+preview method in each request. For device placement and convolution settings,
+see [backend selection](../guides/backend.md).
diff --git a/docs/models/wan.md b/docs/models/wan.md
index ac0f4b9..1b46955 100644
--- a/docs/models/wan.md
+++ b/docs/models/wan.md
@@ -1,120 +1,364 @@
-# How to Use
-
-Wan models require `-M vid_gen`, including single-frame generation. `--video-frames` alone does not select video mode. Library callers must use `generate_video()` instead of `generate_image()`.
+# Wan
+
+Wan 2.1 and 2.2 support video generation with task-specific checkpoints for text,
+images, audio, and VACE conditioning.
+
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Wan2.1 T2V 1.3B | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/tree/main/split_files/diffusion_models) | `--diffusion-model` | Match the task and variant |
+| Wan2.1 T2V 14B | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/tree/main/split_files/diffusion_models)<br>[gguf](https://huggingface.co/city96/Wan2.1-T2V-14B-gguf/tree/main) | `--diffusion-model` | Match the task and variant |
+| Wan2.1 I2V 14B 480P | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/tree/main/split_files/diffusion_models)<br>[gguf](https://huggingface.co/city96/Wan2.1-I2V-14B-480P-gguf/tree/main) | `--diffusion-model` | Match the task and variant |
+| Wan2.1 I2V 14B 720P | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/tree/main/split_files/diffusion_models)<br>[gguf](https://huggingface.co/city96/Wan2.1-I2V-14B-720P-gguf/tree/main) | `--diffusion-model` | Match the task and variant |
+| Wan2.1 FLF2V 14B 720P | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/tree/main/split_files/diffusion_models)<br>[gguf](https://huggingface.co/city96/Wan2.1-FLF2V-14B-720P-gguf/tree/main) | `--diffusion-model` | Match the task and variant |
+| Wan2.1 VACE 1.3B | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/tree/main/split_files/diffusion_models)<br>[gguf](https://huggingface.co/calcuis/wan-1.3b-gguf/tree/main) | `--diffusion-model` | Match the task and variant |
+| Wan2.1 VACE 14B | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/tree/main/split_files/diffusion_models)<br>[gguf](https://huggingface.co/QuantStack/Wan2.1_14B_VACE-GGUF/tree/main) | `--diffusion-model` | Match the task and variant |
+| Wan2.2 TI2V 5B | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.2_ComfyUI_Repackaged/tree/main/split_files/diffusion_models)<br>[gguf](https://huggingface.co/QuantStack/Wan2.2-TI2V-5B-GGUF/tree/main) | `--diffusion-model` | Match the task and variant |
+| Wan2.2 T2V A14B | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.2_ComfyUI_Repackaged/tree/main/split_files/diffusion_models)<br>[gguf](https://huggingface.co/QuantStack/Wan2.2-T2V-A14B-GGUF/tree/main) | `--diffusion-model` | Match the task and variant |
+| Wan2.2 I2V A14B | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.2_ComfyUI_Repackaged/tree/main/split_files/diffusion_models)<br>[gguf](https://huggingface.co/QuantStack/Wan2.2-I2V-A14B-GGUF/tree/main) | `--diffusion-model` | Match the task and variant |
+| Wan2.2 S2V 14B | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.2_ComfyUI_Repackaged/tree/main/split_files/diffusion_models)<br>[gguf](https://huggingface.co/QuantStack/Wan2.2-S2V-14B-GGUF/tree/main)<br>[int8_convrot safetensors](https://huggingface.co/noctrex/Wan2.2-S2V-14B-int8_convrot) | `--diffusion-model` | Match the task and variant |
+| Wan2.2 VACE-Fun A14B | [safetensors](https://huggingface.co/alibaba-pai/Wan2.2-VACE-Fun-A14B)<br>[gguf](https://huggingface.co/QuantStack/Wan2.2-VACE-Fun-A14B-GGUF/tree/main) | `--diffusion-model` | Match the task and variant |
+| wan_2.1_vae (for all the wan model except Wan2.2 TI2V 5B) | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/blob/main/split_files/vae/wan_2.1_vae.safetensors) | `--vae` | Match the model family |
+| wan_2.2_vae (for Wan2.2 TI2V 5B only) | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.2_ComfyUI_Repackaged/blob/main/split_files/vae/wan2.2_vae.safetensors) | `--vae` | Match the model family |
+| umt5_xxl | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/blob/main/split_files/text_encoders/umt5_xxl_fp16.safetensors)<br>[gguf](https://huggingface.co/city96/umt5-xxl-encoder-gguf/tree/main) | `--t5xxl` | Required for the indicated task |
+| clip_vison_h (for Wan2.1 I2V/FLF2V only) | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/blob/main/split_files/clip_vision/clip_vision_h.safetensors) | `--clip_vision` | Required for the indicated task |
+| audio_encoder (for Wan2.2 S2V only) | [safetensors](https://huggingface.co/Comfy-Org/Wan_2.2_ComfyUI_Repackaged/blob/main/split_files/audio_encoders/wav2vec2_large_english_fp16.safetensors) | `--audio-encoder` | Required for the indicated task |
+
+Use the Wan 2.2 VAE only for TI2V 5B; other variants use the matching Wan 2.1
+VAE shown above. Wan 2.2 A14B T2V/I2V use separate high-noise and low-noise
+transformers; load both, using `--high-noise-diffusion-model` for the high-noise
+file. For lower VAE memory use, see [tiny autoencoders](taesd.md).
+
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Wan 2.1 T2V (`wan21-t2v`) | `diffusion_model`, `t5xxl`, `vae`, `tae` |
+| Wan 2.1 I2V (`wan21-i2v`) | `diffusion_model`, `t5xxl`, `vae`, `tae`, `clip_vision` |
+| Wan 2.1 FLF2V 14B (`wan21-flf2v`) | `diffusion_model`, `t5xxl`, `clip_vision`, `vae`, `tae` |
+| Wan 2.1 VACE 1.3B / 14B (`wan21-vace`) | `diffusion_model`, `t5xxl`, `vae`, `tae` |
+| Wan 2.2 T2V A14B (`wan22-t2v`) | `diffusion_model`, `high_noise_diffusion_model`, `t5xxl`, `vae`, `tae` |
+| Wan 2.2 I2V A14B (`wan22-i2v`) | `diffusion_model`, `high_noise_diffusion_model`, `t5xxl`, `vae`, `tae` |
+| Wan 2.2 S2V 14B (`wan22-s2v`) | `diffusion_model`, `t5xxl`, `audio_encoder`, `vae`, `tae` |
+| Wan 2.2 TI2V 5B (`wan22-ti2v-5b`) | `diffusion_model`, `t5xxl`, `vae`, `tae` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Wan2.1 T2V 1.3B
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\wan2.1_t2v_1.3B_fp16.safetensors `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "a lovely cat" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ --flow-shift 3.0 `
+ -W 832 `
+ -H 480 `
+ --video-frames 33 `
+ -v
+```
-## Download weights
-
-- Download Wan
- - Wan2.1
- - Wan2.1 T2V 1.3B
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/tree/main/split_files/diffusion_models
- - Wan2.1 T2V 14B
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/city96/Wan2.1-T2V-14B-gguf/tree/main
- - Wan2.1 I2V 14B 480P
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/city96/Wan2.1-I2V-14B-480P-gguf/tree/main
- - Wan2.1 I2V 14B 720P
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/city96/Wan2.1-I2V-14B-720P-gguf/tree/main
- - Wan2.1 FLF2V 14B 720P
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/city96/Wan2.1-FLF2V-14B-720P-gguf/tree/main
- - Wan2.1 VACE 1.3B
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/calcuis/wan-1.3b-gguf/tree/main
- - Wan2.1 VACE 14B
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/QuantStack/Wan2.1_14B_VACE-GGUF/tree/main
- - Wan2.2
- - Wan2.2 TI2V 5B
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.2_ComfyUI_Repackaged/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/QuantStack/Wan2.2-TI2V-5B-GGUF/tree/main
- - Wan2.2 T2V A14B
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.2_ComfyUI_Repackaged/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/QuantStack/Wan2.2-T2V-A14B-GGUF/tree/main
- - Wan2.2 I2V A14B
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.2_ComfyUI_Repackaged/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/QuantStack/Wan2.2-I2V-A14B-GGUF/tree/main
- - Wan2.2 S2V 14B
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.2_ComfyUI_Repackaged/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/QuantStack/Wan2.2-S2V-14B-GGUF/tree/main
- - int8_convrot safetensors: https://huggingface.co/noctrex/Wan2.2-S2V-14B-int8_convrot
- - Wan2.2 VACE-Fun A14B
- - safetensors: https://huggingface.co/alibaba-pai/Wan2.2-VACE-Fun-A14B
- - gguf: https://huggingface.co/QuantStack/Wan2.2-VACE-Fun-A14B-GGUF/tree/main
-- Download vae
- - wan_2.1_vae (for all the wan model except Wan2.2 TI2V 5B)
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/blob/main/split_files/vae/wan_2.1_vae.safetensors
- - wan_2.2_vae (for Wan2.2 TI2V 5B only)
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.2_ComfyUI_Repackaged/blob/main/split_files/vae/wan2.2_vae.safetensors
-
- > Wan models vae requires really much VRAM! If you do not have enough VRAM, please try tae instead, though the results may be poorer. For tae usage, please refer to [taesd](taesd.md)
-
-- Download umt5_xxl
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/blob/main/split_files/text_encoders/umt5_xxl_fp16.safetensors
- - gguf: https://huggingface.co/city96/umt5-xxl-encoder-gguf/tree/main
-
-- Download clip_vison_h (for Wan2.1 I2V/FLF2V only)
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/blob/main/split_files/clip_vision/clip_vision_h.safetensors
-
-- Download audio_encoder (for Wan2.2 S2V only)
- - safetensors: https://huggingface.co/Comfy-Org/Wan_2.2_ComfyUI_Repackaged/blob/main/split_files/audio_encoders/wav2vec2_large_english_fp16.safetensors
-
-
-## Examples
-
-### Wan2.1 T2V 1.3B
-
-```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.1_t2v_1.3B_fp16.safetensors --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --video-frames 33 --flow-shift 3.0
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/wan2.1_t2v_1.3B_fp16.safetensors \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "a lovely cat" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ --flow-shift 3.0 \
+ -W 832 \
+ -H 480 \
+ --video-frames 33 \
+ -v
```
<video src=../../assets/wan/Wan2.1_1.3B_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
-### Wan2.1 T2V 14B
-
+#### Wan2.1 T2V 14B
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\wan2.1-t2v-14b-Q8_0.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "a lovely cat" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ --flow-shift 3.0 `
+ -W 832 `
+ -H 480 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.1-t2v-14b-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --offload-to-cpu --video-frames 33 --flow-shift 3.0
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/wan2.1-t2v-14b-Q8_0.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "a lovely cat" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ --flow-shift 3.0 \
+ -W 832 \
+ -H 480 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/wan/Wan2.1_14B_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
-
-
-### Wan2.1 I2V 14B
-
+#### Wan2.1 I2V 14B
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\wan2.1-i2v-14b-480p-Q8_0.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ --clip_vision ..\models\clip_vision\clip_vision_h.safetensors `
+ -p "a lovely cat" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ -i ..\inputs\cat_with_sd_cpp_42.png `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ --flow-shift 3.0 `
+ -W 480 `
+ -H 832 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.1-i2v-14b-480p-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf --clip_vision ..\models\clip_vision\clip_vision_h.safetensors -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 480 -H 832 --video-frames 33 --offload-to-cpu -i ..\assets\cat_with_sd_cpp_42.png --flow-shift 3.0
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/wan2.1-i2v-14b-480p-Q8_0.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ --clip_vision ../models/clip_vision/clip_vision_h.safetensors \
+ -p "a lovely cat" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ -i ../inputs/cat_with_sd_cpp_42.png \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ --flow-shift 3.0 \
+ -W 480 \
+ -H 832 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/wan/Wan2.1_14B_i2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
-### Wan2.2 T2V A14B
-
+#### Wan2.2 T2V A14B
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-LowNoise-Q8_0.gguf `
+ --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-HighNoise-Q8_0.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "a lovely cat" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ --cfg-scale 3.5 `
+ --sampling-method euler `
+ --steps 10 `
+ --high-noise-cfg-scale 3.5 `
+ --high-noise-sampling-method euler `
+ --high-noise-steps 8 `
+ --flow-shift 3.0 `
+ -W 832 `
+ -H 480 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-LowNoise-Q8_0.gguf --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-HighNoise-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 3.5 --sampling-method euler --steps 10 --high-noise-cfg-scale 3.5 --high-noise-sampling-method euler --high-noise-steps 8 -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --offload-to-cpu --video-frames 33 --flow-shift 3.0
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/Wan2.2-T2V-A14B-LowNoise-Q8_0.gguf \
+ --high-noise-diffusion-model ../models/diffusion_models/Wan2.2-T2V-A14B-HighNoise-Q8_0.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "a lovely cat" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ --cfg-scale 3.5 \
+ --sampling-method euler \
+ --steps 10 \
+ --high-noise-cfg-scale 3.5 \
+ --high-noise-sampling-method euler \
+ --high-noise-steps 8 \
+ --flow-shift 3.0 \
+ -W 832 \
+ -H 480 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/wan/Wan2.2_14B_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
-### Wan2.2 I2V A14B
-
+#### Wan2.2 I2V A14B
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\Wan2.2-I2V-A14B-LowNoise-Q8_0.gguf `
+ --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-I2V-A14B-HighNoise-Q8_0.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "a lovely cat" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ -i ..\inputs\cat_with_sd_cpp_42.png `
+ --cfg-scale 3.5 `
+ --sampling-method euler `
+ --steps 10 `
+ --high-noise-cfg-scale 3.5 `
+ --high-noise-sampling-method euler `
+ --high-noise-steps 8 `
+ --flow-shift 3.0 `
+ -W 832 `
+ -H 480 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.2-I2V-A14B-LowNoise-Q8_0.gguf --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-I2V-A14B-HighNoise-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 3.5 --sampling-method euler --steps 10 --high-noise-cfg-scale 3.5 --high-noise-sampling-method euler --high-noise-steps 8 -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --offload-to-cpu --video-frames 33 --offload-to-cpu -i ..\assets\cat_with_sd_cpp_42.png --flow-shift 3.0
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/Wan2.2-I2V-A14B-LowNoise-Q8_0.gguf \
+ --high-noise-diffusion-model ../models/diffusion_models/Wan2.2-I2V-A14B-HighNoise-Q8_0.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "a lovely cat" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ -i ../inputs/cat_with_sd_cpp_42.png \
+ --cfg-scale 3.5 \
+ --sampling-method euler \
+ --steps 10 \
+ --high-noise-cfg-scale 3.5 \
+ --high-noise-sampling-method euler \
+ --high-noise-steps 8 \
+ --flow-shift 3.0 \
+ -W 832 \
+ -H 480 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/wan/Wan2.2_14B_i2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
-### Wan2.2 S2V 14B
+#### Wan2.2 S2V 14B
Audio-driven video (speech-to-video). The reference image (`-i`) is the speaker
portrait, `--audio` is the driving audio track and `--audio-encoder` is the
wav2vec2 audio encoder. Wan2.2 S2V requires the wan_2.1 vae (16 channel), not
the wan2.2 vae.
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\wan2.2_s2v-14B-Q8_0.gguf `
+ --audio-encoder ..\models\text_encoders\audio_encoders\wav2vec2_large_english_fp16.safetensors `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "a person is talking" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ -i ..\inputs\cat_with_sd_cpp_42.png `
+ --audio .\input\speech.wav `
+ --cfg-scale 6.0 `
+ --steps 20 `
+ --sampling-method euler `
+ --flow-shift 3.0 `
+ -W 832 `
+ -H 480 `
+ --video-frames 81 `
+ --offload-to-cpu `
+ --vae-tiling `
+ -v
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.2_s2v-14B-Q8_0.gguf --audio-encoder ..\models\audio_encoders\wav2vec2_large_english_fp16.safetensors --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a person is talking" --cfg-scale 6.0 --steps 20 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --offload-to-cpu --vae-tiling --video-frames 81 -i ..\assets\cat_with_sd_cpp_42.png --audio .\input\speech.wav --flow-shift 3.0
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/wan2.2_s2v-14B-Q8_0.gguf \
+ --audio-encoder ../models/text_encoders/audio_encoders/wav2vec2_large_english_fp16.safetensors \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "a person is talking" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ -i ../inputs/cat_with_sd_cpp_42.png \
+ --audio ./input/speech.wav \
+ --cfg-scale 6.0 \
+ --steps 20 \
+ --sampling-method euler \
+ --flow-shift 3.0 \
+ -W 832 \
+ -H 480 \
+ --video-frames 81 \
+ --offload-to-cpu \
+ --vae-tiling \
+ -v
```
Notes:
@@ -140,146 +384,680 @@ Notes:
`--cfg-scale 1.0`. Use the **low_noise** variant;
the high_noise variant produces artifacts on S2V:
- ```
- --lora-model-dir ..\models\loras
- -p "...<lora:lightx2v-Wan2.2-T2V-A14B-4steps-lora-rank64-Seko-V2.0-low_noise:1.0>"
- --cfg-scale 1.0 --steps 4
- ```
+**Windows (PowerShell) arguments**
- Expect some quality/dynamics loss compared to the full 20-step run.
+```text
+--lora-model-dir ..\models\loras `
+ -p "...<lora:lightx2v-Wan2.2-T2V-A14B-4steps-lora-rank64-Seko-V2.0-low_noise:1.0>" `
+ --cfg-scale 1.0 `
+ --steps 4
+```
-### Wan2.2 T2V A14B T2I
+**Linux/macOS arguments**
+```text
+--lora-model-dir ../models/loras \
+ -p "...<lora:lightx2v-Wan2.2-T2V-A14B-4steps-lora-rank64-Seko-V2.0-low_noise:1.0>" \
+ --cfg-scale 1.0 \
+ --steps 4
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-LowNoise-Q8_0.gguf --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-HighNoise-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 3.5 --sampling-method euler --steps 10 --high-noise-cfg-scale 3.5 --high-noise-sampling-method euler --high-noise-steps 8 -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --offload-to-cpu --flow-shift 3.0
-```
-
-<img width="832" height="480" alt="Wan2 2_14B_t2i" src="../../assets/wan/Wan2.2_14B_t2i.png" />
-### Wan2.2 T2V 14B with Lora
+ Expect some quality/dynamics loss compared to the full 20-step run.
-```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-LowNoise-Q8_0.gguf --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-HighNoise-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat<lora:wan2.2_t2v_lightx2v_4steps_lora_v1.1_low_noise:1><lora:|high_noise|wan2.2_t2v_lightx2v_4steps_lora_v1.1_high_noise:1>" --cfg-scale 3.5 --sampling-method euler --steps 4 --high-noise-cfg-scale 3.5 --high-noise-sampling-method euler --high-noise-steps 4 -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --offload-to-cpu --lora-model-dir ..\models\loras --video-frames 33 --flow-shift 3.0
+#### Wan2.2 T2V A14B T2I
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-LowNoise-Q8_0.gguf `
+ --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-HighNoise-Q8_0.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "a lovely cat" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ --cfg-scale 3.5 `
+ --sampling-method euler `
+ --steps 10 `
+ --high-noise-cfg-scale 3.5 `
+ --high-noise-sampling-method euler `
+ --high-noise-steps 8 `
+ --flow-shift 3.0 `
+ -W 832 `
+ -H 480 `
+ --offload-to-cpu `
+ -v
```
-<video src=../../assets/wan/Wan2.2_14B_t2v_lora.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/Wan2.2-T2V-A14B-LowNoise-Q8_0.gguf \
+ --high-noise-diffusion-model ../models/diffusion_models/Wan2.2-T2V-A14B-HighNoise-Q8_0.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "a lovely cat" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ --cfg-scale 3.5 \
+ --sampling-method euler \
+ --steps 10 \
+ --high-noise-cfg-scale 3.5 \
+ --high-noise-sampling-method euler \
+ --high-noise-steps 8 \
+ --flow-shift 3.0 \
+ -W 832 \
+ -H 480 \
+ --offload-to-cpu \
+ -v
+```
+<img width="832" height="480" alt="Wan2 2_14B_t2i" src="../../assets/wan/Wan2.2_14B_t2i.png" />
+#### Wan2.2 T2V 14B with Lora
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-LowNoise-Q8_0.gguf `
+ --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-HighNoise-Q8_0.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ --lora-model-dir ..\models\loras `
+ -p "a lovely cat<lora:wan2.2_t2v_lightx2v_4steps_lora_v1.1_low_noise:1><lora:|high_noise|wan2.2_t2v_lightx2v_4steps_lora_v1.1_high_noise:1>" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ --cfg-scale 3.5 `
+ --sampling-method euler `
+ --steps 4 `
+ --high-noise-cfg-scale 3.5 `
+ --high-noise-sampling-method euler `
+ --high-noise-steps 4 `
+ --flow-shift 3.0 `
+ -W 832 `
+ -H 480 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ -v
+```
-### Wan2.2 TI2V 5B
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/Wan2.2-T2V-A14B-LowNoise-Q8_0.gguf \
+ --high-noise-diffusion-model ../models/diffusion_models/Wan2.2-T2V-A14B-HighNoise-Q8_0.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ --lora-model-dir ../models/loras \
+ -p "a lovely cat<lora:wan2.2_t2v_lightx2v_4steps_lora_v1.1_low_noise:1><lora:|high_noise|wan2.2_t2v_lightx2v_4steps_lora_v1.1_high_noise:1>" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ --cfg-scale 3.5 \
+ --sampling-method euler \
+ --steps 4 \
+ --high-noise-cfg-scale 3.5 \
+ --high-noise-sampling-method euler \
+ --high-noise-steps 4 \
+ --flow-shift 3.0 \
+ -W 832 \
+ -H 480 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ -v
+```
-#### T2V
+<video src=../../assets/wan/Wan2.2_14B_t2v_lora.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+#### Wan2.2 TI2V 5B
+
+##### T2V
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\wan2.2_ti2v_5B_fp16.safetensors `
+ --vae ..\models\vae\wan2.2_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "a lovely cat" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ --flow-shift 3.0 `
+ -W 480 `
+ -H 832 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.2_ti2v_5B_fp16.safetensors --vae ..\models\vae\wan2.2_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 480 -H 832 --offload-to-cpu --video-frames 33 --flow-shift 3.0
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/wan2.2_ti2v_5B_fp16.safetensors \
+ --vae ../models/vae/wan2.2_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "a lovely cat" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ --flow-shift 3.0 \
+ -W 480 \
+ -H 832 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/wan/Wan2.2_5B_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
-#### I2V
-
+##### I2V
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\wan2.2_ti2v_5B_fp16.safetensors `
+ --vae ..\models\vae\wan2.2_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "a lovely cat" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ -i ..\inputs\cat_with_sd_cpp_42.png `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ --flow-shift 3.0 `
+ -W 480 `
+ -H 832 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.2_ti2v_5B_fp16.safetensors --vae ..\models\vae\wan2.2_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 480 -H 832 --offload-to-cpu --video-frames 33 -i ..\assets\cat_with_sd_cpp_42.png --flow-shift 3.0
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/wan2.2_ti2v_5B_fp16.safetensors \
+ --vae ../models/vae/wan2.2_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "a lovely cat" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ -i ../inputs/cat_with_sd_cpp_42.png \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ --flow-shift 3.0 \
+ -W 480 \
+ -H 832 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/wan/Wan2.2_5B_i2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
TI2V 5B can decode multiple latent frames together when temporal tiling is enabled. For example, `--temporal-tiling --vae-tiling --vae-tile-size 256x256 --extra-tiling-args "temporal_tile_frames=4,temporal_decode_frames=2"` keeps up to four latent frames in each temporal tile and decodes up to two at once, with spatial tiles of 256×256 pixels. `temporal_decode_frames` defaults to `1`, preserving frame-by-frame decoding; other model versions ignore it. Increasing it requires more memory. Adjust the spatial tile size to fit the available memory.
-### Wan2.1 FLF2V 14B
-
-```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.1-flf2v-14b-720p-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf --clip_vision ..\models\clip_vision\clip_vision_h.safetensors -p "glass flower blossom" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 480 -H 832 --video-frames 33 --offload-to-cpu --init-img ..\..\ComfyUI\input\start_image.png --end-img ..\..\ComfyUI\input\end_image.png --flow-shift 3.0
+#### Wan2.1 FLF2V 14B
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\wan2.1-flf2v-14b-720p-Q8_0.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ --clip_vision ..\models\clip_vision\clip_vision_h.safetensors `
+ -p "glass flower blossom" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ --init-img ..\inputs\start_image.png `
+ --end-img ..\inputs\end_image.png `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ --flow-shift 3.0 `
+ -W 480 `
+ -H 832 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ -v
```
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/wan2.1-flf2v-14b-720p-Q8_0.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ --clip_vision ../models/clip_vision/clip_vision_h.safetensors \
+ -p "glass flower blossom" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ --init-img ../inputs/start_image.png \
+ --end-img ../inputs/end_image.png \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ --flow-shift 3.0 \
+ -W 480 \
+ -H 832 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ -v
+```
<video src=../../assets/wan/Wan2.1_14B_flf2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
-### Wan2.2 FLF2V 14B
-
+#### Wan2.2 FLF2V 14B
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\Wan2.2-I2V-A14B-LowNoise-Q8_0.gguf `
+ --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-I2V-A14B-HighNoise-Q8_0.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "glass flower blossom" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ --init-img ..\inputs\start_image.png `
+ --end-img ..\inputs\end_image.png `
+ --cfg-scale 3.5 `
+ --sampling-method euler `
+ --steps 10 `
+ --high-noise-cfg-scale 3.5 `
+ --high-noise-sampling-method euler `
+ --high-noise-steps 8 `
+ --flow-shift 3.0 `
+ -W 480 `
+ -H 832 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.2-I2V-A14B-LowNoise-Q8_0.gguf --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-I2V-A14B-HighNoise-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf --cfg-scale 3.5 --sampling-method euler --steps 10 --high-noise-cfg-scale 3.5 --high-noise-sampling-method euler --high-noise-steps 8 -v -p "glass flower blossom" -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 480 -H 832 --video-frames 33 --offload-to-cpu --init-img ..\..\ComfyUI\input\start_image.png --end-img ..\..\ComfyUI\input\end_image.png --flow-shift 3.0
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/Wan2.2-I2V-A14B-LowNoise-Q8_0.gguf \
+ --high-noise-diffusion-model ../models/diffusion_models/Wan2.2-I2V-A14B-HighNoise-Q8_0.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "glass flower blossom" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ --init-img ../inputs/start_image.png \
+ --end-img ../inputs/end_image.png \
+ --cfg-scale 3.5 \
+ --sampling-method euler \
+ --steps 10 \
+ --high-noise-cfg-scale 3.5 \
+ --high-noise-sampling-method euler \
+ --high-noise-steps 8 \
+ --flow-shift 3.0 \
+ -W 480 \
+ -H 832 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/wan/Wan2.2_14B_flf2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
-### Wan2.1 VACE 1.3B
-
-#### T2V
-
+#### Wan2.1 VACE 1.3B
+
+##### T2V
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\wan2.1-vace-1.3b-q8_0.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "a lovely cat" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ -W 832 `
+ -H 480 `
+ --video-frames 1 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.1-vace-1.3b-q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --video-frames 1 --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/wan2.1-vace-1.3b-q8_0.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "a lovely cat" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ -W 832 \
+ -H 480 \
+ --video-frames 1 \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/wan/Wan2.1_1.3B_vace_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
-
-#### R2V
-
+##### R2V
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\wan2.1-vace-1.3b-q8_0.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "a lovely cat" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ -i ..\inputs\cat_with_sd_cpp_42.png `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ -W 832 `
+ -H 480 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.1-vace-1.3b-q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 -i ..\assets\cat_with_sd_cpp_42.png --video-frames 33 --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/wan2.1-vace-1.3b-q8_0.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "a lovely cat" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ -i ../inputs/cat_with_sd_cpp_42.png \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ -W 832 \
+ -H 480 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/wan/Wan2.1_1.3B_vace_r2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+##### V2V
-#### V2V
+**Windows (PowerShell)**
-```
+```powershell
mkdir post+depth
-ffmpeg -i ..\..\ComfyUI\input\post+depth.mp4 -qscale:v 1 -vf fps=8 post+depth\frame_%04d.jpg
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.1-vace-1.3b-q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "The girl is dancing in a sea of flowers, slowly moving her hands. There is a close - up shot of her upper body. The character is surrounded by other transparent glass flowers in the style of Nicoletta Ceccoli, creating a beautiful, surreal, and emotionally expressive movie scene with a white. transparent feel and a dreamyl atmosphere." --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 480 -H 832 -i ..\..\ComfyUI\input\dance_girl.jpg --control-video ./post+depth --video-frames 33 --offload-to-cpu
+ffmpeg -i ....ComfyUIinputpost+depth.mp4 -qscale:v 1 -vf fps=8 post+depthframe_%04d.jpg
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\wan2.1-vace-1.3b-q8_0.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "The girl is dancing in a sea of flowers, slowly moving her hands. There is a close - up shot of her upper body. The character is surrounded by other transparent glass flowers in the style of Nicoletta Ceccoli, creating a beautiful, surreal, and emotionally expressive movie scene with a white. transparent feel and a dreamyl atmosphere." `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ -i ..\inputs\dance_girl.jpg `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ -W 480 `
+ -H 832 `
+ --video-frames 33 `
+ --control-video ./post+depth `
+ --offload-to-cpu `
+ -v
```
-<video src=../../assets/wan/Wan2.1_1.3B_vace_v2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+**Linux/macOS**
-### Wan2.1 VACE 14B
+```sh
+mkdir post+depth
+ffmpeg -i ....ComfyUIinputpost+depth.mp4 -qscale:v 1 -vf fps=8 post+depthframe_%04d.jpg
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/wan2.1-vace-1.3b-q8_0.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "The girl is dancing in a sea of flowers, slowly moving her hands. There is a close - up shot of her upper body. The character is surrounded by other transparent glass flowers in the style of Nicoletta Ceccoli, creating a beautiful, surreal, and emotionally expressive movie scene with a white. transparent feel and a dreamyl atmosphere." \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ -i ../inputs/dance_girl.jpg \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ -W 480 \
+ -H 832 \
+ --video-frames 33 \
+ --control-video ./post+depth \
+ --offload-to-cpu \
+ -v
+```
-#### T2V
+<video src=../../assets/wan/Wan2.1_1.3B_vace_v2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+#### Wan2.1 VACE 14B
+
+##### T2V
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\Wan2.1_14B_VACE-Q8_0.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "a lovely cat" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ -W 832 `
+ -H 480 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.1_14B_VACE-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --video-frames 33 --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/Wan2.1_14B_VACE-Q8_0.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "a lovely cat" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ -W 832 \
+ -H 480 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/wan/Wan2.1_14B_vace_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
-
-#### R2V
-
+##### R2V
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\Wan2.1_14B_VACE-Q8_0.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "a lovely cat" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ -i ..\inputs\cat_with_sd_cpp_42.png `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ -W 832 `
+ -H 480 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.1_14B_VACE-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 -i ..\assets\cat_with_sd_cpp_42.png --video-frames 33 --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/Wan2.1_14B_VACE-Q8_0.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "a lovely cat" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ -i ../inputs/cat_with_sd_cpp_42.png \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ -W 832 \
+ -H 480 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/wan/Wan2.1_14B_vace_r2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
-
-
-#### V2V
-
+##### V2V
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\Wan2.1_14B_VACE-Q8_0.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "The girl is dancing in a sea of flowers, slowly moving her hands. There is a close - up shot of her upper body. The character is surrounded by other transparent glass flowers in the style of Nicoletta Ceccoli, creating a beautiful, surreal, and emotionally expressive movie scene with a white. transparent feel and a dreamyl atmosphere." `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ -i ..\inputs\dance_girl.jpg `
+ --cfg-scale 6.0 `
+ --sampling-method euler `
+ -W 480 `
+ -H 832 `
+ --video-frames 33 `
+ --control-video ./post+depth `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.1_14B_VACE-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "The girl is dancing in a sea of flowers, slowly moving her hands. There is a close - up shot of her upper body. The character is surrounded by other transparent glass flowers in the style of Nicoletta Ceccoli, creating a beautiful, surreal, and emotionally expressive movie scene with a white. transparent feel and a dreamyl atmosphere." --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 480 -H 832 -i ..\..\ComfyUI\input\dance_girl.jpg --control-video ./post+depth --video-frames 33 --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/Wan2.1_14B_VACE-Q8_0.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "The girl is dancing in a sea of flowers, slowly moving her hands. There is a close - up shot of her upper body. The character is surrounded by other transparent glass flowers in the style of Nicoletta Ceccoli, creating a beautiful, surreal, and emotionally expressive movie scene with a white. transparent feel and a dreamyl atmosphere." \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ -i ../inputs/dance_girl.jpg \
+ --cfg-scale 6.0 \
+ --sampling-method euler \
+ -W 480 \
+ -H 832 \
+ --video-frames 33 \
+ --control-video ./post+depth \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/wan/Wan2.1_14B_vace_v2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
-### Wan2.2 VACE-Fun A14B
+#### Wan2.2 VACE-Fun A14B
VACE-Fun runs as a MoE pair: `--diffusion-model` takes the low-noise expert and
`--high-noise-diffusion-model` the high-noise one. Reference-to-video uses `-i`
for the reference image, same as Wan2.1 VACE.
-#### R2V
-
+##### R2V
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ -M vid_gen `
+ --diffusion-model ..\models\diffusion_models\Wan2.2-VACE-Fun-A14B-low-noise-Q8_0.gguf `
+ --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-VACE-Fun-A14B-high-noise-Q8_0.gguf `
+ --vae ..\models\vae\wan_2.1_vae.safetensors `
+ --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf `
+ -p "a lovely cat" `
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" `
+ -i ..\inputs\cat_with_sd_cpp_42.png `
+ --cfg-scale 3.5 `
+ --sampling-method euler `
+ --steps 10 `
+ --high-noise-cfg-scale 3.5 `
+ --high-noise-sampling-method euler `
+ --high-noise-steps 8 `
+ -W 832 `
+ -H 480 `
+ --video-frames 33 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.2-VACE-Fun-A14B-low-noise-Q8_0.gguf --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-VACE-Fun-A14B-high-noise-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 3.5 --sampling-method euler --steps 10 --high-noise-cfg-scale 3.5 --high-noise-sampling-method euler --high-noise-steps 8 -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 -i ..\assets\cat_with_sd_cpp_42.png --video-frames 33 --offload-to-cpu
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ -M vid_gen \
+ --diffusion-model ../models/diffusion_models/Wan2.2-VACE-Fun-A14B-low-noise-Q8_0.gguf \
+ --high-noise-diffusion-model ../models/diffusion_models/Wan2.2-VACE-Fun-A14B-high-noise-Q8_0.gguf \
+ --vae ../models/vae/wan_2.1_vae.safetensors \
+ --t5xxl ../models/text_encoders/umt5-xxl-encoder-Q8_0.gguf \
+ -p "a lovely cat" \
+ -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" \
+ -i ../inputs/cat_with_sd_cpp_42.png \
+ --cfg-scale 3.5 \
+ --sampling-method euler \
+ --steps 10 \
+ --high-noise-cfg-scale 3.5 \
+ --high-noise-sampling-method euler \
+ --high-noise-steps 8 \
+ -W 832 \
+ -H 480 \
+ --video-frames 33 \
+ --offload-to-cpu \
+ -v
```
<video src=../../assets/wan/Wan2.2_A14B_vace_r2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
-#### T2V
+##### T2V
Same command without `-i` (VACE context is synthesized from an empty control
video, like Wan2.1 VACE t2v).
> On GPUs with ~12 GB VRAM, VACE also needs `--vae-tiling` — the control-video
> encode can exceed the budget otherwise.
+
+## Notes and limitations
+
+Wan models require `-M vid_gen`, including single-frame generation. `--video-frames` alone does not select video mode. Library callers must use `generate_video()` instead of `generate_image()`.
+
+Use the task-specific input and sampling settings in each example. VAE
+encoding and decoding can require substantial memory; see
+[performance and memory usage](../guides/performance.md).
diff --git a/docs/models/z_image.md b/docs/models/z_image.md
index 6913ece..9b39e3d 100644
--- a/docs/models/z_image.md
+++ b/docs/models/z_image.md
@@ -1,41 +1,112 @@
-# How to Use
+# Z-Image
+
+Z-Image and Z-Image-Turbo generate images from text using Qwen3 4B and the FLUX VAE.
You can run Z-Image with stable-diffusion.cpp on GPUs with 4GB of VRAM — or even less.
-## Download weights
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Z-Image-Turbo | [Safetensors](https://huggingface.co/Comfy-Org/z_image_turbo/tree/main/split_files/diffusion_models)<br>[GGUF](https://huggingface.co/leejet/Z-Image-Turbo-GGUF/tree/main) | `--diffusion-model` | Choose matching variant |
+| Z-Image | [Safetensors](https://huggingface.co/Comfy-Org/z_image/tree/main/split_files/diffusion_models)<br>[GGUF](https://huggingface.co/unsloth/Z-Image-GGUF/tree/main) | `--diffusion-model` | Choose matching variant |
+| vae | [Safetensors](https://huggingface.co/black-forest-labs/FLUX.1-schnell/tree/main) | `--vae` | Use matching VAE |
+| Qwen3 4b | [Safetensors](https://huggingface.co/Comfy-Org/z_image_turbo/tree/main/split_files/text_encoders)<br>[GGUF](https://huggingface.co/unsloth/Qwen3-4B-Instruct-2507-GGUF/tree/main) | `--llm` | Use matching text encoder |
+
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Z-Image (`z-image`) | `diffusion_model`, `llm`, `vae`, `tae` |
+| Z-Image Turbo (`z-image-turbo`) | `diffusion_model`, `llm`, `vae`, `tae` |
-- Download Z-Image-Turbo
- - safetensors: https://huggingface.co/Comfy-Org/z_image_turbo/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/leejet/Z-Image-Turbo-GGUF/tree/main
-- Download Z-Image
- - safetensors: https://huggingface.co/Comfy-Org/z_image/tree/main/split_files/diffusion_models
- - gguf: https://huggingface.co/unsloth/Z-Image-GGUF/tree/main
-- Download vae
- - safetensors: https://huggingface.co/black-forest-labs/FLUX.1-schnell/tree/main
-- Download Qwen3 4b
- - safetensors: https://huggingface.co/Comfy-Org/z_image_turbo/tree/main/split_files/text_encoders
- - gguf: https://huggingface.co/unsloth/Qwen3-4B-Instruct-2507-GGUF/tree/main
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
-## Examples
+### CLI
-### Z-Image-Turbo
+#### Z-Image-Turbo
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\z_image_turbo-Q3_K.gguf `
+ --vae ..\models\vae\ae.sft `
+ --llm ..\models\text_encoders\Qwen3-4B-Instruct-2507-Q4_K_M.gguf `
+ -p "A cinematic, melancholic photograph of a solitary hooded figure walking through a sprawling, rain-slicked metropolis at night. The city lights are a chaotic blur of neon orange and cool blue, reflecting on the wet asphalt. The scene evokes a sense of being a single component in a vast machine. Superimposed over the image in a sleek, modern, slightly glitched font is the philosophical quote: 'THE CITY IS A CIRCUIT BOARD, AND I AM A BROKEN TRANSISTOR.' -- moody, atmospheric, profound, dark academic" `
+ --cfg-scale 1.0 `
+ --steps 8 `
+ -H 1024 `
+ -W 512 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model z_image_turbo-Q3_K.gguf --vae ..\models\vae\ae.sft --llm ..\models\text_encoders\Qwen3-4B-Instruct-2507-Q4_K_M.gguf -p "A cinematic, melancholic photograph of a solitary hooded figure walking through a sprawling, rain-slicked metropolis at night. The city lights are a chaotic blur of neon orange and cool blue, reflecting on the wet asphalt. The scene evokes a sense of being a single component in a vast machine. Superimposed over the image in a sleek, modern, slightly glitched font is the philosophical quote: 'THE CITY IS A CIRCUIT BOARD, AND I AM A BROKEN TRANSISTOR.' -- moody, atmospheric, profound, dark academic" --cfg-scale 1.0 -v --offload-to-cpu -H 1024 -W 512 --steps 8
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/z_image_turbo-Q3_K.gguf \
+ --vae ../models/vae/ae.sft \
+ --llm ../models/text_encoders/Qwen3-4B-Instruct-2507-Q4_K_M.gguf \
+ -p "A cinematic, melancholic photograph of a solitary hooded figure walking through a sprawling, rain-slicked metropolis at night. The city lights are a chaotic blur of neon orange and cool blue, reflecting on the wet asphalt. The scene evokes a sense of being a single component in a vast machine. Superimposed over the image in a sleek, modern, slightly glitched font is the philosophical quote: 'THE CITY IS A CIRCUIT BOARD, AND I AM A BROKEN TRANSISTOR.' -- moody, atmospheric, profound, dark academic" \
+ --cfg-scale 1.0 \
+ --steps 8 \
+ -H 1024 \
+ -W 512 \
+ --offload-to-cpu \
+ -v
```
<img width="256" alt="z-image example" src="../../assets/z_image/q3_K.png" />
-### Z-Image-Base
+#### Z-Image-Base
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\z_image_bf16.safetensors `
+ --vae ..\models\vae\ae.sft `
+ --llm ..\models\text_encoders\qwen_3_4b.safetensors `
+ -p "A cinematic, melancholic photograph of a solitary hooded figure walking through a sprawling, rain-slicked metropolis at night. The city lights are a chaotic blur of neon orange and cool blue, reflecting on the wet asphalt. The scene evokes a sense of being a single component in a vast machine. Superimposed over the image in a sleek, modern, slightly glitched font is the philosophical quote: 'THE CITY IS A CIRCUIT BOARD, AND I AM A BROKEN TRANSISTOR.' -- moody, atmospheric, profound, dark academic" `
+ --cfg-scale 5.0 `
+ -H 1024 `
+ -W 512 `
+ --offload-to-cpu `
+ -v
```
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\z_image_bf16.safetensors --vae ..\models\vae\ae.sft --llm ..\models\text_encoders\qwen_3_4b.safetensors -p "A cinematic, melancholic photograph of a solitary hooded figure walking through a sprawling, rain-slicked metropolis at night. The city lights are a chaotic blur of neon orange and cool blue, reflecting on the wet asphalt. The scene evokes a sense of being a single component in a vast machine. Superimposed over the image in a sleek, modern, slightly glitched font is the philosophical quote: 'THE CITY IS A CIRCUIT BOARD, AND I AM A BROKEN TRANSISTOR.' -- moody, atmospheric, profound, dark academic" --cfg-scale 5.0 -v --offload-to-cpu -H 1024 -W 512
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/z_image_bf16.safetensors \
+ --vae ../models/vae/ae.sft \
+ --llm ../models/text_encoders/qwen_3_4b.safetensors \
+ -p "A cinematic, melancholic photograph of a solitary hooded figure walking through a sprawling, rain-slicked metropolis at night. The city lights are a chaotic blur of neon orange and cool blue, reflecting on the wet asphalt. The scene evokes a sense of being a single component in a vast machine. Superimposed over the image in a sleek, modern, slightly glitched font is the philosophical quote: 'THE CITY IS A CIRCUIT BOARD, AND I AM A BROKEN TRANSISTOR.' -- moody, atmospheric, profound, dark academic" \
+ --cfg-scale 5.0 \
+ -H 1024 \
+ -W 512 \
+ --offload-to-cpu \
+ -v
```
<img width="256" alt="z-image example" src="../../assets/z_image/base_bf16.png" />
-## Comparison of Different Quantization Types
+#### Comparison of Different Quantization Types
| bf16 | q8_0 | q6_K | q5_0 | q4_K | q4_0 | q3_K | q2_K|
|---|---|---|---|---|---|---|---|
-| <img width="256" alt="bf16" src="../../assets/z_image/bf16.png" /> | <img width="256" alt="q8_0" src="../../assets/z_image/q8_0.png" /> | <img width="256" alt="q6_K" src="../../assets/z_image/q6_K.png" /> | <img width="256" alt="q5_0" src="../../assets/z_image/q5_0.png" /> | <img width="256" alt="q4_K" src="../../assets/z_image/q4_K.png" /> | <img width="256" alt="q4_0" src="../../assets/z_image/q4_0.png" /> | <img width="256" alt="q3_K" src="../../assets/z_image/q3_K.png" /> | <img width="256" alt="q2_K" src="../../assets/z_image/q2_K.png" /> |
\ No newline at end of file
+| <img width="256" alt="bf16" src="../../assets/z_image/bf16.png" /> | <img width="256" alt="q8_0" src="../../assets/z_image/q8_0.png" /> | <img width="256" alt="q6_K" src="../../assets/z_image/q6_K.png" /> | <img width="256" alt="q5_0" src="../../assets/z_image/q5_0.png" /> | <img width="256" alt="q4_K" src="../../assets/z_image/q4_K.png" /> | <img width="256" alt="q4_0" src="../../assets/z_image/q4_0.png" /> | <img width="256" alt="q3_K" src="../../assets/z_image/q3_K.png" /> | <img width="256" alt="q2_K" src="../../assets/z_image/q2_K.png" /> |
diff --git a/docs/models/z_image_l2p.md b/docs/models/z_image_l2p.md
index a7836f5..c572af8 100644
--- a/docs/models/z_image_l2p.md
+++ b/docs/models/z_image_l2p.md
@@ -1,21 +1,72 @@
# Z-Image L2P
-[L2P](https://nju-pcalab.github.io/projects/L2P/) (Latent-to-Pixel) transfers Z-Image-Turbo to pixel space. The VAE is replaced by 16x16 patch tokenization on RGB pixels and a small convolutional local decoder that turns the last DiT hidden states back into pixels, so no VAE is needed. The text encoder is the Qwen3-4B used by Z-Image-Turbo.
+[L2P](https://nju-pcalab.github.io/projects/L2P/) (Latent-to-Pixel) generates images
+directly in pixel space using Z-Image-Turbo and Qwen3 4B. No VAE is required.
-## Download weights
+## Model files
-- Download L2P (1K)
- - safetensors: https://huggingface.co/zhen-nan/L2P/tree/main
-- Download Qwen3 4b
- - safetensors: https://huggingface.co/Comfy-Org/z_image_turbo/tree/main/split_files/text_encoders
- - gguf: https://huggingface.co/unsloth/Qwen3-4B-Instruct-2507-GGUF/tree/main
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| L2P (1K) | [Safetensors](https://huggingface.co/zhen-nan/L2P/tree/main) | `--diffusion-model` | Required |
+| Qwen3 4b | [Safetensors](https://huggingface.co/Comfy-Org/z_image_turbo/tree/main/split_files/text_encoders)<br>[GGUF](https://huggingface.co/unsloth/Qwen3-4B-Instruct-2507-GGUF/tree/main) | `--llm` | Use matching text encoder |
-## Text-to-image
+## Usage
+
+CLI examples use the [shared path and shell conventions](README.md#example-conventions).
+
+### Web UI
+
+Follow the [Web UI guide](../../examples/server/README.md#web-ui) to start the
+server, then select the recipe matching your weights. Fill the component slots
+below and click **Load models**.
+Use the files and compatibility requirements in [Model files](#model-files).
+
+| Recipe | Component slots |
+| --- | --- |
+| Z-Image L2P (`z-image-l2p`) | `diffusion_model`, `llm` |
+
+Slot IDs correspond to CLI component options: `diffusion_model` uses
+`--diffusion-model`, `llm` uses `--llm`, and `model` uses `-m` / `--model`.
+Select optional components when required by your checkpoint or task.
+
+### CLI
+
+#### Text-to-image
Do not pass `--vae`. Image dimensions must be multiples of 16. The reference pipeline uses 30 steps with a CFG scale of 2.0.
The released checkpoint keeps part of the transformer in F32. Pass `--type bf16` to load it in BF16, as the reference pipeline runs it; this reduces the diffusion model from about 18.6 GB to 11.8 GB.
-```bash
-.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\model-1k-merge.safetensors --llm ..\models\text_encoders\qwen_3_4b.safetensors -p "an origami pig on fire in the middle of a dark room with a pentagram on the floor" --cfg-scale 2.0 --steps 30 --sampling-method euler -W 1024 -H 1024 --type bf16 -v -o z_image_l2p.png
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe `
+ --diffusion-model ..\models\diffusion_models\model-1k-merge.safetensors `
+ --llm ..\models\text_encoders\qwen_3_4b.safetensors `
+ --type bf16 `
+ -p "an origami pig on fire in the middle of a dark room with a pentagram on the floor" `
+ --cfg-scale 2.0 `
+ --steps 30 `
+ --sampling-method euler `
+ -W 1024 `
+ -H 1024 `
+ -v `
+ -o z_image_l2p.png
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --diffusion-model ../models/diffusion_models/model-1k-merge.safetensors \
+ --llm ../models/text_encoders/qwen_3_4b.safetensors \
+ --type bf16 \
+ -p "an origami pig on fire in the middle of a dark room with a pentagram on the floor" \
+ --cfg-scale 2.0 \
+ --steps 30 \
+ --sampling-method euler \
+ -W 1024 \
+ -H 1024 \
+ -v \
+ -o z_image_l2p.png
```
diff --git a/examples/cli/README.md b/examples/cli/README.md
index 2072e1c..78dd25a 100644
--- a/examples/cli/README.md
+++ b/examples/cli/README.md
@@ -1,8 +1,16 @@
# Usage
-For detailed command-line arguments, run:
+From the build directory, show the full list of command-line arguments:
-```bash
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe -h
+```
+
+**Linux/macOS**
+
+```sh
./bin/sd-cli -h
```
@@ -37,13 +45,50 @@ input defaults, downstream model processing, mask alignment, and examples.
Metadata mode inspects PNG, JPEG, WebP (including animated WebP), AVI, WebM, and Matroska
container metadata without loading any model. Use `--image` for both images and videos:
-```bash
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-cli.exe -M metadata --image .\output.png
+.\bin\Release\sd-cli.exe `
+ -M metadata `
+ --image .\output.jpg `
+ --metadata-format json
+.\bin\Release\sd-cli.exe -M metadata --image .\output.webm
+.\bin\Release\sd-cli.exe `
+ -M metadata `
+ --image .\output.avi `
+ --metadata-format json
+.\bin\Release\sd-cli.exe `
+ -M metadata `
+ --image .\output.png `
+ --metadata-raw
+.\bin\Release\sd-cli.exe `
+ -M metadata `
+ --image .\output.png `
+ --metadata-all
+```
+
+**Linux/macOS**
+
+```sh
./bin/sd-cli -M metadata --image ./output.png
-./bin/sd-cli -M metadata --image ./output.jpg --metadata-format json
+./bin/sd-cli \
+ -M metadata \
+ --image ./output.jpg \
+ --metadata-format json
./bin/sd-cli -M metadata --image ./output.webm
-./bin/sd-cli -M metadata --image ./output.avi --metadata-format json
-./bin/sd-cli -M metadata --image ./output.png --metadata-raw
-./bin/sd-cli -M metadata --image ./output.png --metadata-all
+./bin/sd-cli \
+ -M metadata \
+ --image ./output.avi \
+ --metadata-format json
+./bin/sd-cli \
+ -M metadata \
+ --image ./output.png \
+ --metadata-raw
+./bin/sd-cli \
+ -M metadata \
+ --image ./output.png \
+ --metadata-all
```
For completely black or white images or videos, NaNs, and the `--linear-scale` /
diff --git a/examples/server/README.md b/examples/server/README.md
index 33b256e..6b6e750 100644
--- a/examples/server/README.md
+++ b/examples/server/README.md
@@ -1,70 +1,74 @@
-# Model selection
+# stable-diffusion.cpp Server
-Start without model arguments to select models in the web UI:
+`sd-server` provides a Web UI for image and video generation, model management,
+and HTTP APIs. Download or build the server before starting; see the
+[build guide](../../docs/build.md) and [frontend build instructions](#build-with-frontend).
-```sh
-sd-server --model-dir ./models
-```
+- [Web UI](#web-ui): start the server, load a model, and generate.
+- [Model management](#model-management): model directories, recipes, and startup models.
+- [Server configuration](#server-configuration): launcher settings, network, logging, and help.
+- [API](#api): native and compatibility endpoints.
+- [Frontend development](#frontend-development): build or customize the Web UI.
-From a source checkout, you can also use `sh ./start-server.sh` on Linux/macOS
-or `.\start-server.bat` on Windows. The launchers look for the server relative
-to the script: beside the script, then in `bin/Release/`, `bin/`,
-`build/bin/Release/`, and `build/bin/`, in that order.
-For a different build directory, set `SD_SERVER_PATH` to the executable path:
+## Web UI
-```sh
-SD_SERVER_PATH="./build_vulkan/bin/sd-server" sh ./start-server.sh --listen-port 8080
-```
+### Start the server
+
+From the repository root, start the launcher. It finds the server executable
+and uses the repository's `models/` directory:
+
+**Windows (PowerShell)**
```powershell
-$env:SD_SERVER_PATH = ".\build_vulkan\bin\Release\sd-server.exe"
-.\start-server.bat --listen-port 8080
+.\start-server.bat
```
-Binary release archives include both launchers. Keep the launchers under version
-control and put personal settings in a separate file beside them:
+You can also double-click `start-server.bat` in File Explorer to start the
+server. Keep the console window open while using the Web UI.
-- Windows batch: `start-server.local.bat`
-- Linux/macOS: `start-server.local.sh`
+**Linux/macOS**
-These local files are ignored by Git and excluded from release archives. They
-are loaded automatically after the launcher's defaults. They can override
-`SD_SERVER_PATH`, `MODEL_DIR`, and `COMMANDLINE_ARGS`; there is no need to edit
-the tracked launchers. For example:
+```sh
+sh ./start-server.sh
+```
-```bat
-@echo off
-set "MODEL_DIR=D:\stable-diffusion-webui\models"
-set "COMMANDLINE_ARGS=--listen-port 8080 --offload-to-cpu"
+To start the executable directly instead, run from the build directory:
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-server.exe --model-dir ..\models
```
+**Linux/macOS**
+
```sh
-MODEL_DIR="/data/stable-diffusion-webui/models"
-COMMANDLINE_ARGS="--listen-port 8080 --offload-to-cpu"
+./bin/sd-server --model-dir ../models
```
-Each launcher prints the resolved command before execution and forwards the
-server's exit code.
-
-`SD_SERVER_PATH` inherits the environment value by default; leave it empty for
-automatic discovery, or set it in the local file to select another executable.
-Settings are applied in this order: launcher defaults, local configuration,
-then invocation arguments. Repeated `--model-dir` arguments add roots, so they
-do not replace the `MODEL_DIR` root. Local configuration files are shell scripts
-and use the corresponding shell's syntax.
+The Windows path above is for a Visual Studio Release build. Adjust the path
+for another build configuration or an extracted release archive. Open
+<http://127.0.0.1:1234/> after the server starts, and keep the server running
+while using the browser.
+
+### Load a model
+
+1. Download the weights and required components listed in the matching
+ [model guide](../../docs/models/README.md). Put them in the category folders
+ under `models/`, such as `checkpoints/`, `diffusion_models/`, `text_encoders/`,
+ `tokenizers/`, and `vae/`. See [Model directories](#model-directories) below.
+2. Click **Model** below the prompt to open model selection.
+3. Choose the matching **Recipe**. Keep **Apply recipe defaults** enabled to
+ start with that recipe's generation settings.
+4. Select each component in its named field: for example, **Diffusion model**,
+ the model-specific text encoder field, and **VAE**. Required fields have an
+ asterisk. A VAE/TAE requirement needs one compatible decoder. Match all files
+ to the chosen checkpoint and variant, as described in its model guide.
+5. If a file is missing from a dropdown, check its category folder and click
+ **Refresh files & recipes**. Selectors support searching by name or path.
+6. Click **Load models** and wait for loading to finish. Selecting a recipe or
+ file alone does not reload the model.
-The launchers preserve the current working directory, so the default
-`MODEL_DIR="./models"` is relative to where you start the launcher. Arguments
-passed when invoking the launcher follow these defaults. Repeated `--model-dir`
-arguments add search roots rather than replacing `MODEL_DIR`; set `MODEL_DIR` in
-the local configuration to change the first root. Other single-value options can override the defaults.
-In the shell script, `COMMANDLINE_ARGS` is a
-whitespace-separated list; pass values containing spaces as quoted arguments
-when invoking the script. `MODEL_DIR` itself supports spaces in both scripts.
-A leading `--version` bypasses the configured defaults. An explicit
-`SD_SERVER_PATH` is used without falling back to another build if it is invalid.
-
-Choose a recipe, select the required component files, and click **Load models**.
Recipe and component selectors support searching by name or relative file ID.
Use the arrow keys and Enter to select, or Escape to cancel a search. With
**Apply recipe defaults** enabled, selecting a recipe immediately applies its
@@ -74,123 +78,56 @@ switching recipes. This preference defaults to enabled and is saved locally.
Model loading and server-info refreshes do not reapply defaults or reset the form.
Recipes declaring `video_frames` also switch the form to Video Generation;
other recipes switch to Image Generation. Generation is enabled after the
-selected recipe is loaded. Changing a selection does not reload the model
-until you click Load.
+selected recipe is loaded.
+
+The model button shows elapsed loading time and keeps the final time after
+success or failure, including after a page refresh.
+
+### Generate an image or video
+
+1. Enter a prompt, for example `a lovely cat` for an image model.
+2. Open **Sample & Guidance** to set **Method**, **Scheduler**, **Steps**, and
+ **CFG Scale** when the model guide specifies values different from the recipe
+ defaults. Set the output dimensions in **Aspect Ratio & Resolution**.
+3. Supply inputs for the chosen task. Editing recipes use **Reference Images**;
+ IP-Adapter uses **IP-Adapter Image**. For image-to-video, use video generation
+ and upload a **Start Frame**; add an **End Frame** only for a compatible
+ first/last-frame workflow. Set the video length and FPS as required by the model.
+4. Click **Generate**. Wait for denoising, decoding, and output encoding to
+ finish, then preview or save the result. Sampling reaching 100% does not mean
+ decoding has finished.
The generation status bar shows the current stage and elapsed time even when
Preview Mode is `none`. During sampling it shows completed steps for the current
pass; prompt encoding and VAE decoding show an activity indicator when their
-total work is unknown. Sampling reaching 100% does not mean the job is finished:
-decoding, ADetailer, and output encoding may still follow.
-The canvas keeps the submitted output aspect ratio, and stage changes keep the
-same layout. Editing the next request's resolution does not resize the current
-preview or result.
-
-The server can also start with the existing model arguments shown below;
-existing API clients then work without selecting a recipe. The UI automatically
-selects **Command-line model (all features)** and uses the startup generation
-defaults. This runtime-only recipe exposes all controls for the supported
-image/video mode. Selecting another recipe previews a model switch; selecting
-the command-line entry again restores its generation defaults. The entry is
-removed when the command-line context is unloaded or replaced.
+total work is unknown. The canvas keeps the submitted output aspect ratio, and
+stage changes keep the same layout. Editing the next request's resolution does
+not resize the current preview or result.
-Built-in recipes cover SD 1/2/3/3.5, SDXL and distilled checkpoints;
-FLUX 1/2/3, Chroma, Qwen Image and editing variants; Z-Image, Anima, ERNIE,
-LENS, PiD and other supported image families; AnimateDiff, Wan, LTX,
-HunyuanVideo, LingBot Video and MiniMax-H3. Model-specific text encoder
-labels identify the expected encoder family and size. Loading a video model enables **Video Generation**; I2V also requires a
-start image. The model button below the prompt opens model and recipe selection.
-Its status summary shows elapsed loading time from the status API and keeps the final
-time after success or failure, including after a page refresh.
-Built-ins are embedded in the
-binary from [recipes/](recipes/), with one JSON file per recipe. Adding or
-editing a built-in requires rebuilding the server. User recipes are read from
-`<model-dir>/recipes/*.json`. A valid user recipe with the same ID replaces
-the entire built-in recipe. Across roots, the first valid user recipe wins;
-overrides are logged. Duplicate user IDs within one root are rejected; invalid
-recipes are reported without removing a valid recipe from another root or the
-built-in version. Slots need only `id` and
-`required`; the server supplies labels and search directories. Use `label`
-only when a recipe needs a more specific display name.
+### LoRAs
-Recipes use `features` to enable specialized controls and `disabled_features`
-to turn off shared defaults. Disabled features take precedence. The UI hides
-unsupported fields, empty sections and irrelevant sampler/cache options, and
-omits hidden values from generation requests. See the
-[feature declarations](api.md#recipe-feature-declarations) for the defaults
-and complete list of supported names.
+To apply a LoRA, open **LoRA**, select a compatible file, and set its
+**Strength**. Place files under `models/loras/` or `models/Lora/`. Browser
+requests use this selector; prompt tags such as `<lora:name:1>` are CLI syntax
+and are not parsed by the native server API.
-Built-in additions and changes must follow the [recipe policy](recipes/README.md).
-Split recipes by task weights or added capabilities, not by style or acceleration
-LoRAs. Quantizations, file formats and compatible layer-count variants share a
-recipe. Native encoders, projectors and connectors stay in the model's recipe.
-Community editing recipes require selecting the matching LoRA separately; a
-recipe does not enable it automatically.
+## Model management
-See [generation defaults and sources](recipes/defaults.md) for the selected
-publisher recommendations and reference-code defaults, with step defaults capped
-at 20. Recipes link to the
-original publisher's Hugging Face repository where one is available. DiT
-recipes default to Euler, except for models requiring a specialized sampler.
+### Model directories
-Compatible recipes offer a TAE slot alongside VAE. When the checkpoint does not
-bundle a VAE, select at least one of VAE or TAE. The Models panel shows a reminder
-below the model selectors until this requirement is met. A selected TAE is used for
-encoding and decoding, including when a full VAE is also selected; use complete,
-model-compatible TAE weights rather than decoder-only preview weights. Qwen
-Image 2.1 uses the same recipe for its full VAE and TAEQI2.1 alternatives.
-
-The following variants have dedicated recipes:
+Repeat `--model-dir` to share multiple model directories, including an existing
+SD WebUI model directory. Run these examples from the build directory:
-| Model | Recipe IDs / notes |
-| --- | --- |
-| Z-Image L2P | `z-image-l2p`; no VAE |
-| LLaDA-Image | `llada-image` (base) and `llada-image-turbo`; use matching encoders and connectors |
-| PixArt Alpha | `pixart-alpha-512`, `pixart-alpha-1024`; Alpha VAE scale and positional settings |
-| PiD / PiD 1.5 | `pid` / `pid-15` for Flux or Z-Image VAE; append `-sd3`, `-flux2`, or `-qwen-image` for other latent formats |
-| SDXL adapters | `sdxl-ip-adapter` supports classic and Plus ViT-H adapters; `sdxl-controlnet` requires compatible SDXL weights |
-| FLUX.1 Fill / Depth | `flux1-fill` uses Init Image and Mask Image; `flux1-depth` uses a precomputed depth map in Control Image |
-| SD2 / SDXL inpainting | `sd2-inpainting`, `sdxl-inpainting` |
-| SD-Turbo | `sd-turbo`; single-file SD2.1-derived checkpoint |
-| Community editing LoRAs | `anima-edit`, `krea2-raw-edit`, `krea2-turbo-edit`; apply a matching LoRA after loading |
-| HunyuanVideo 1.5 | `hunyuan-video-15-t2v`, `hunyuan-video-15-i2v`; choose the task's checkpoint |
-| Wan 2.1 / compatible single Wan 2.2 experts | `wan21-t2v`, `wan21-i2v`; the I2V recipe also accepts compatible SkyReels V2 weights |
-| Qwen Image 2.1 Turbo | `qwen-image-21-turbo`; standalone Turbo weights with the fixed 8-step schedule, Euler and CFG 1 |
-| MOSS Image | `moss-image-base`, `moss-image-sft`; choose the corresponding checkpoint |
-
-PiD always requires a reference image and uses the first one. Its recipes expose
-reference inputs rather than ordinary image-to-image inputs. IP-Adapter recipes
-expose a separate IP-Adapter image and strength. FLUX Canny/Depth consume Control
-Image directly without a separate ControlNet; the UI does not calculate edge
-or depth maps. Their strength is controlled by guidance, not ControlNet strength.
-Krea2 edit recipes use the default `krea2_ostris_edit` reference preset, so the
-editing LoRA must match that convention. Ordinary Anima and Krea2 recipes do not
-expose reference-image editing inputs.
-
-Fill/Depth guidance defaults follow the [Diffusers FLUX documentation](https://huggingface.co/docs/diffusers/api/pipelines/flux).
-SD-Turbo uses the [model card's one-step configuration](https://huggingface.co/stabilityai/sd-turbo),
-with CFG disabled using scale 1 in sd.cpp.
-
-SVD is not included: legacy model recognition and UNet branches remain, but the
-current runner/conditioning setup does not provide a dedicated SVD image-conditioning
-path. Adding a recipe alone would not establish a working SVD pipeline.
+**Windows (PowerShell)**
-Reference images, masks, audio, first/last video frames, and generation options
-such as upscaling remain generation inputs. Hardware and memory options remain
-startup arguments. Tiny SD/Tiny SD2 and Diffusers LCM directories must first be
-converted into single-file checkpoints for the file catalog. LCM checkpoints
-and LoRAs use the matching SD family recipe; select LCM sampling and adjust
-steps/CFG for the chosen weights.
-Metadata inspection, conversion, standalone upscaling and ADetailer are CLI
-workflows rather than model-loading recipes. ESRGAN and LTX latent upscalers
-are selected through generation upscaling settings with `--hires-upscalers-dir`;
-textual inversion uses the startup `--embd-dir` option.
+```powershell
+.\bin\Release\sd-server.exe --model-dir ..\models --model-dir D:\stable-diffusion-webui\models
+```
-Repeat `--model-dir` to share multiple model directories, including an existing
-SD WebUI model directory:
+**Linux/macOS**
```sh
-sd-server --model-dir ./models --model-dir /data/stable-diffusion-webui/models
+./bin/sd-server --model-dir ../models --model-dir /data/stable-diffusion-webui/models
```
With no `--model-dir`, the server uses `./models`. Explicit roots replace that
@@ -216,6 +153,7 @@ models/
checkpoints/
diffusion_models/
text_encoders/
+ tokenizers/
vae/
clip_vision/
loras/
@@ -242,6 +180,132 @@ model root. Use `--lora-model-dir` to replace automatic discovery with one
explicit LoRA directory. Duplicate names remain separate selectable entries. The LoRA selectors support
searching by name or path with the same keyboard controls as model selectors.
+### Recipes
+
+A recipe describes a model's components, supported capabilities, and generation
+defaults. See the [model guides](../../docs/models/README.md) for compatible
+recipes and weights. Text encoder labels in the selectors identify the expected
+encoder family and size.
+
+#### Built-in and user recipes
+
+Built-in recipes are embedded in the binary from [recipes/](recipes/), with one JSON file per recipe. Adding or
+editing a built-in requires rebuilding the server. User recipes are read from
+`<model-dir>/recipes/*.json`. A valid user recipe with the same ID replaces
+the entire built-in recipe. Across roots, the first valid user recipe wins;
+overrides are logged. Duplicate user IDs within one root are rejected; invalid
+recipes are reported without removing a valid recipe from another root or the
+built-in version. Slots need only `id` and
+`required`; the server supplies labels and search directories. Use `label`
+only when a recipe needs a more specific display name.
+
+Built-in additions and changes must follow the [recipe policy](recipes/README.md).
+Split recipes by task weights or added capabilities, not by style or acceleration
+LoRAs. Quantizations, file formats and compatible layer-count variants share a
+recipe. Native encoders, projectors and connectors stay in the model's recipe.
+Community editing recipes require selecting the matching LoRA separately; a
+recipe does not enable it automatically.
+
+#### Generation defaults and controls
+
+See [generation defaults and sources](recipes/defaults.md) for the selected
+publisher recommendations and reference-code defaults, with step defaults capped
+at 20. Recipes link to the
+original publisher's Hugging Face repository where one is available. DiT
+recipes default to Euler, except for models requiring a specialized sampler.
+
+Recipes use `features` to enable specialized controls and `disabled_features`
+to turn off shared defaults. Disabled features take precedence. The UI hides
+unsupported fields, empty sections and irrelevant sampler/cache options, and
+omits hidden values from generation requests. See the
+[feature declarations](api.md#recipe-feature-declarations) for the defaults
+and complete list of supported names.
+
+#### VAE and TAE
+
+Compatible recipes offer a TAE slot alongside VAE. When the checkpoint does not
+bundle a VAE, select at least one of VAE or TAE. The Models panel shows a reminder
+below the model selectors until this requirement is met. A selected TAE is used for
+encoding and decoding, including when a full VAE is also selected; use complete,
+model-compatible TAE weights rather than decoder-only preview weights. Qwen
+Image 2.1 uses the same recipe for its full VAE and TAEQI2.1 alternatives.
+
+### Models loaded at startup
+
+You can pass the same model-loading arguments used by `sd-cli` to `sd-server`.
+For example, run this Z-Image Turbo configuration from the build directory:
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-server.exe `
+ --model-dir ..\models `
+ --diffusion-model ..\models\diffusion_models\z_image_turbo_bf16.safetensors `
+ --vae ..\models\vae\ae.sft `
+ --llm ..\models\text_encoders\qwen_3_4b.safetensors `
+ --offload-to-cpu `
+ -v `
+ --cfg-scale 1.0
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-server \
+ --model-dir ../models \
+ --diffusion-model ../models/diffusion_models/z_image_turbo_bf16.safetensors \
+ --vae ../models/vae/ae.sft \
+ --llm ../models/text_encoders/qwen_3_4b.safetensors \
+ --offload-to-cpu \
+ -v \
+ --cfg-scale 1.0
+```
+
+`--diffusion-model`, `--vae`, and `--llm` select the model components.
+`--offload-to-cpu` keeps weights in RAM when possible to reduce VRAM pressure,
+`-v` enables verbose logging, and `--cfg-scale 1.0` sets the default CFG scale.
+
+API clients can use the model loaded at startup without selecting a recipe.
+The UI automatically selects **Command-line model (all features)** and uses the
+startup generation defaults. This runtime-only recipe exposes all controls for the supported
+image/video mode. Selecting another recipe previews a model switch; selecting
+the command-line entry again restores its generation defaults. The entry is
+removed when the command-line context is unloaded or replaced.
+
+#### Identity inputs
+
+The browser currently has no PhotoMaker identity-image or PuLID identity-embedding
+upload control. Prepare the inputs using the
+[PhotoMaker](../../docs/models/photo_maker.md) or [PuLID](../../docs/models/pulid.md)
+guide, then supply them when starting the server. From the build directory, for example:
+
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-server.exe --model-dir ..\models --pm-id-images-dir ..\inputs\identity
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-server --model-dir ../models --pm-id-images-dir ../inputs/identity
+```
+
+Select the PhotoMaker recipe and weights in the browser. For PhotoMaker v2, also
+pass `--pm-id-embed-path` with the prepared embedding file. For PuLID, use
+`--pulid-id-embedding` instead of the PhotoMaker input argument, then select the
+PuLID recipe and weights. These startup inputs are inherited by generation requests.
+
+#### Sharded checkpoints
+
+For a checkpoint loaded from a complete repository directory, pass its model
+loading arguments when starting `sd-server`, as in the model's CLI example.
+Keep the index, tokenizer, and all shards together. The browser then uses
+**Command-line model (all features)** for the model loaded at startup; selecting
+an individual shard in a recipe dropdown does not load the whole repository.
+
+### Switching models
+
The server keeps one model context loaded. Loading or unloading is rejected
while generation requests or queued jobs are pending. A switch validates the
selection before unloading the old context, then loads the replacement.
@@ -253,146 +317,186 @@ request parameters take precedence.
See [the API reference](api.md#model-management) for recipe fields, supported
slots, management endpoints, and compatibility behavior.
-# Example
+### Limitations
-The following example starts `sd-server` with a standalone diffusion model, VAE, and LLM text encoder:
+Tiny SD/Tiny SD2 and Diffusers LCM directories must first be
+converted into single-file checkpoints for the file catalog. LCM checkpoints
+and LoRAs use the matching SD family recipe; select LCM sampling and adjust
+steps/CFG for the chosen weights.
+Metadata inspection, conversion, standalone upscaling and ADetailer are CLI
+workflows rather than model-loading recipes. ESRGAN and LTX latent upscalers
+are selected through generation upscaling settings with `--hires-upscalers-dir`;
+textual inversion uses the startup `--embd-dir` option.
-```
-.\bin\Release\sd-server.exe --diffusion-model ..\models\diffusion_models\z_image_turbo_bf16.safetensors --vae ..\models\vae\ae.sft --llm ..\models\text_encoders\qwen_3_4b.safetensors --offload-to-cpu -v --cfg-scale 1.0
-```
+SVD is not available through the current server pipeline.
-What this example does:
+## Server configuration
-* `--diffusion-model` selects the standalone diffusion model
-* `--vae` selects the VAE decoder
-* `--llm` selects the text encoder / language model used by this pipeline
-* `--offload-to-cpu` reduces VRAM pressure by keeping weights in RAM when possible
-* `-v` enables verbose logging (equivalent to `--log-level verbose`)
-* `--cfg-scale 1.0` sets the default CFG scale for generation
+Reference images, masks, audio, first/last video frames, and generation options
+such as upscaling are supplied with generation requests. Hardware and memory
+options are startup arguments and apply to subsequent model loads.
-Logging defaults to `info`. Use `--log-level <level>` to select `debug`, `verbose`,
-`info`, `warn`, or `error` (from most to least detailed). Each level includes
-messages at that level and all less detailed levels. `-v` and `--verbose` are
-equivalent to `--log-level verbose`. If repeated, the last logging option wins.
+### Launcher settings
-After the server starts successfully:
+Both source checkouts and binary release archives include `start-server.bat`
+and `start-server.sh`. The launchers search for the server beside the script,
+then in `bin/Release/`, `bin/`, `build/bin/Release/`, and `build/bin/`, in that order.
+They print the resolved command and forward the server's exit code.
-* the web UI is available at `http://127.0.0.1:1234/`
-* the native async API is available under `/sdcpp/v1/...`
-* the compatibility APIs are available under `/v1/...` and `/sdapi/v1/...`
+#### Custom executable
-If you want to use a different host or port, pass:
+For a different build directory, set `SD_SERVER_PATH` to the executable path.
+Run from the repository root:
-```bash
---listen-ip <ip> --listen-port <port>
+**Windows (PowerShell)**
+
+```powershell
+$env:SD_SERVER_PATH = ".\build_vulkan\bin\Release\sd-server.exe"
+.\start-server.bat --listen-port 8080
```
-The native async job queue can be tuned with:
+**Linux/macOS**
-```bash
---max-pending-jobs <count> --completed-ttl-seconds <seconds>
+```sh
+SD_SERVER_PATH="./build_vulkan/bin/sd-server" sh ./start-server.sh --listen-port 8080
```
-`--max-pending-jobs` defaults to 64 and limits how many async jobs may be
-queued or generating. `--completed-ttl-seconds` defaults to 600 and controls
-how long completed jobs remain available through the async API.
+`SD_SERVER_PATH` inherits the environment value by default. Leave it empty for
+automatic discovery. An explicit invalid path does not fall back to another build.
-# Frontend
+#### Local configuration
-## Build with Frontend
+Keep personal settings in a file beside the launchers: `start-server.local.bat`
+on Windows or `start-server.local.sh` on Linux/macOS. These files are ignored by
+Git and excluded from release archives. They are loaded automatically and can
+set `SD_SERVER_PATH`, `MODEL_DIR`, and `COMMANDLINE_ARGS`.
-The server can optionally build the web frontend and embed it into the binary as `gen_index_html.h`.
+**Windows (`start-server.local.bat`)**
-### Requirements
+```bat
+@echo off
+set "MODEL_DIR=D:\stable-diffusion-webui\models"
+set "COMMANDLINE_ARGS=--listen-port 8080 --offload-to-cpu"
+```
-Install the following tools:
+**Linux/macOS (`start-server.local.sh`)**
-* **Node.js** ≥ 20
- https://nodejs.org/
+```sh
+MODEL_DIR="/data/stable-diffusion-webui/models"
+COMMANDLINE_ARGS="--listen-port 8080 --offload-to-cpu"
+```
-* **pnpm** ≥ 10
- Install via npm:
+Settings are applied in this order: launcher defaults, local configuration,
+then invocation arguments. Local files are shell scripts and use the
+corresponding shell's syntax.
-```bash
-npm install -g pnpm
-```
+The launchers preserve the current working directory, so the default
+`MODEL_DIR="./models"` is relative to where you start the launcher. To change
+the first model root, set `MODEL_DIR` in the local configuration. Repeated
+`--model-dir` arguments add search roots; other single-value options can override
+the defaults.
-Verify installation:
+In the shell script, `COMMANDLINE_ARGS` is a whitespace-separated list. Pass
+values containing spaces as quoted invocation arguments instead. `MODEL_DIR`
+itself supports spaces in both scripts. A leading `--version` bypasses the
+configured defaults.
-```bash
-node -v
-pnpm -v
-```
+### Network and job queue
-### Install frontend dependencies
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `--listen-ip <ip>` | `127.0.0.1` | Server listen address |
+| `--listen-port <port>` | `1234` | Server listen port |
+| `--max-pending-jobs <count>` | `64` | Maximum async jobs queued or generating |
+| `--completed-ttl-seconds <seconds>` | `600` | Retention time for completed async jobs |
-Go to the frontend directory and install dependencies:
+### Logging
-```bash
-cd examples/server/frontend
-pnpm install
-```
+Logging defaults to `info`. Use `--log-level <level>` to select `debug`, `verbose`,
+`info`, `warn`, or `error` (from most to least detailed). Each level includes
+messages at that level and all less detailed levels. `-v` and `--verbose` are
+equivalent to `--log-level verbose`. If repeated, the last logging option wins.
-### Build the server with CMake
+### Command-line help
-Enable the frontend build option when configuring CMake:
+Run from the build directory for the complete list of server and generation options:
-```bash
-cmake -B build -DSD_SERVER_BUILD_FRONTEND=ON
-cmake --build build --config Release
+**Windows (PowerShell)**
+
+```powershell
+.\bin\Release\sd-server.exe --help
```
-If `pnpm` is available, the build system will automatically run:
+**Linux/macOS**
-```
-pnpm run build
-pnpm run build:header
+```sh
+./bin/sd-server --help
```
-and embed the generated frontend into the server binary.
+## API
-## Frontend Repository
+The server exposes these API families at the same host and port as the Web UI:
-The web frontend is maintained in a **separate repository**, https://github.com/leejet/sdcpp-webui.
-
-If you want to modify the UI or frontend logic, please submit pull requests to the **frontend repository**.
+| API | Path prefix |
+| --- | --- |
+| Native async API | `/sdcpp/v1/...` |
+| OpenAI-compatible API | `/v1/...` |
+| Stable Diffusion WebUI-compatible API | `/sdapi/v1/...` |
-This repository (`stable-diffusion.cpp`) only vendors the frontend periodically. Changes from the frontend repo are synchronized:
+See the [API reference](api.md) for endpoints, request fields, and examples.
-* approximately **every 1–2 weeks**, or
-* when there are **major frontend updates**
+## Frontend development
-Because of this, frontend changes will **not appear here immediately** after being merged upstream.
+### Build with frontend
-## Using an external frontend
+The server can build the frontend and embed it in the binary. Install
+[Node.js](https://nodejs.org/) 20 or newer and pnpm 10 or newer:
-By default, the server uses the **embedded frontend** generated during the build (`gen_index_html.h`).
+```sh
+npm install -g pnpm
+node -v
+pnpm -v
+```
-You can also serve a custom frontend file instead of the embedded one by using:
+Run the following commands from the repository root. They work in PowerShell
+and POSIX shells. Initialize the frontend submodule if it is missing, then
+configure and build with CMake:
-```bash
---serve-html-path <path-to-index.html>
+```sh
+git submodule update --init examples/server/frontend
+cmake -S . -B build -DSD_SERVER_BUILD_FRONTEND=ON
+cmake --build build --config Release
```
-For example:
+Add the backend options from the [build guide](../../docs/build.md) when
+configuring CMake. The build installs frontend dependencies, runs `pnpm run build`
+and `pnpm run build:header`, and embeds `gen_index_html.h` in `sd-server`.
+If pnpm is unavailable, CMake can use an existing generated header; without
+either, the server builds without the embedded Web UI.
-```bash
-sd-server --serve-html-path ./index.html
-```
+### Using an external frontend
-In this case, the server will load and serve the specified `index.html` file instead of the embedded frontend. This is useful when:
+Use `--serve-html-path` to serve a custom `index.html` instead of the embedded
+frontend. For example, place it at the repository root and run from the build
+directory:
-* developing or testing frontend changes
-* using a custom UI
-* avoiding rebuilding the binary after frontend modifications
+**Windows (PowerShell)**
-# Usage
+```powershell
+.\bin\Release\sd-server.exe --model-dir ..\models --serve-html-path ..\index.html
+```
-For detailed command-line arguments, run:
+**Linux/macOS**
-```bash
-./bin/sd-server -h
+```sh
+./bin/sd-server --model-dir ../models --serve-html-path ../index.html
```
-For completely black or white images or videos, NaNs, and the `--linear-scale` /
-`--attn-scale` startup options, see [Troubleshooting](../../docs/troubleshooting.md).
+This lets you develop or test the frontend without rebuilding the server binary.
+
+### Frontend repository
+
+The Web UI is maintained in the separate
+[sdcpp-webui repository](https://github.com/leejet/sdcpp-webui), included here as
+a Git submodule. Submit UI and frontend logic changes to that repository.
+Changes appear here when the submodule is updated.