diff --git a/docs/animatediff.md b/docs/animatediff.md
deleted file mode 100644
index 80c46ae64f..0000000000
--- a/docs/animatediff.md
+++ /dev/null
@@ -1,171 +0,0 @@
-# AnimateDiff (SD 1.5)
-
-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).
-
-## Download weights
-
-- Motion module (v3, recommended)
- - fp16 safetensors: https://huggingface.co/conrevo/AnimateDiff-A1111/resolve/main/motion_module/mm_sd15_v3.safetensors
- - original checkpoint: https://huggingface.co/guoyww/animatediff/resolve/main/v3_sd15_mm.ckpt
-- SD 1.5 base model
- - any SD 1.5 checkpoint works. `realisticVisionV60B1` and `toonyou_beta3`
- are the ones used in guoyww's reference configs.
-- Domain Adapter LoRA (optional, v3 only, sharpens the base UNet's output
- toward the motion module's trained distribution)
- - ckpt: https://huggingface.co/guoyww/animatediff/resolve/main/v3_sd15_adapter.ckpt
- - place under your `--lora-model-dir` and reference in the prompt as
- `
|
-| Close-up rabbit macro shot |
|
-| Coastline, storm, waves, lightning |
|
-| Old house, storm, forest, night |
|
-
-### v2 (384x384, `mm_sd_v15_v2.ckpt`)
-
-| Prompt | Sample |
-|---------------------------------------|--------|
-| B&W man on stormy coastline |
|
-| Close-up rabbit macro shot |
|
-| Coastline, storm, waves, lightning |
|
-| Old house, storm, forest, night |
|
-
-Motion is strong for scenes with motion cues in the prompt (storm/waves/wind)
-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
-
-Attaching the `v3_sd15_adapter` LoRA sharpens the base UNet output toward
-the training distribution the motion module was fine-tuned against. Same
-prompt, seed, config as above:
-
-
-
-Individual fur strands, glowing inner-ear, and richer forest detail become
-visible compared to the no-LoRA rendering.
-
-```
-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 ...
-
-```
-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
-```
-
-`--strength` controls how far the motion module is allowed to deviate from the init image (higher = more motion, lower = more static).
-
-## Notes
-
-- 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
- motion arc. Frame counts up to 32 are supported by the positional encoding
- but exceed the trained regime and produce more static output.
-- At `--video-frames 1` the motion module is skipped entirely and the output
- is bit-identical to `-M img_gen`. This avoids the single-token
- temporal-attention degeneracy that would otherwise emit an untrained-magnitude
- residual on a single-frame sample.
-- The base UNet is frozen, so character identity and style follow the SD 1.5
- checkpoint you pass to `--model`. LoRAs and prompt weighting attach to the
- base model in the usual way.
-- No mid_block motion module in v3. `mm_sdxl_v10_beta` (SDXL variant) is not
- supported yet.
-- Output is written as MJPEG AVI. Use `--fps` to set playback speed.
diff --git a/docs/boogu_image.md b/docs/boogu_image.md
deleted file mode 100644
index c5ad97dd85..0000000000
--- a/docs/boogu_image.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# How to Use
-
-Boogu Image uses a Boogu diffusion transformer, the FLUX VAE, and Qwen3-VL as the LLM text and vision encoder.
-
-## Download weights
-
-- 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`.
-
-## Examples
-
-### Boogu Image Base
-
-```
-.\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
-```
-
-
-
-### Boogu Image Edit
-
-```
-.\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'"
-```
-
-
\ No newline at end of file
diff --git a/docs/build.md b/docs/build.md
index 575436a218..1533cfb2bc 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -21,25 +21,6 @@ git pull origin master
git submodule update --init --recursive
```
-## MSVC compilation parallelism
-
-MSVC builds limit parallel C/C++ compilation within each project by default.
-For `n` logical processors, the limit is `n` when `n <= 2`, `n - 1` when
-`3 <= n <= 8`, and `n - 2` when `n > 8`. The default is calculated when the
-build directory is first configured with this setting. Override it with
-`-DSD_MSVC_MP_COUNT=4`, or pass `-USD_MSVC_MP_COUNT` to recalculate it.
-
-For Visual Studio builds, keep project-level parallelism at one to avoid
-multiplying the per-project limit:
-
-```shell
-cmake --build build --config Release --parallel 1
-```
-
-This setting controls MSVC's `/MP` option, not CUDA compiler parallelism or a
-hard CPU usage limit. Other build tools, such as Ninja, schedule compilation
-jobs separately; use `cmake --build build --parallel N` to limit those jobs.
-
## Selecting a GGML source tree
By default, sd.cpp builds the patched GGML submodule in `ggml/`. To build with
@@ -120,7 +101,7 @@ cmake --build . --config Release
The sd.cpp SageAttention extension is included when using CUDA with patched
GGML (`SD_USE_UPSTREAM_GGML=OFF`).
-See [SageAttention](sage_attention.md) for GPU requirements and `--sage-attn` usage.
+See [SageAttention](guides/sage_attention.md) for GPU requirements and `--sage-attn` usage.
This provides GPU acceleration using NVIDIA GPU. Make sure to have the CUDA toolkit installed. You can download it from your Linux distro's package manager (e.g. `apt install nvidia-cuda-toolkit`) or from here: [CUDA Toolkit](https://developer.nvidia.com/cuda-downloads). Recommended to have at least 4 GB of VRAM.
@@ -130,6 +111,11 @@ cmake .. -DSD_CUDA=ON
cmake --build . --config Release
```
+When building GGML from source, sd.cpp's CUDA extensions use the same target
+architectures as GGML, including native GPU detection with `GGML_NATIVE=ON`.
+To select target GPUs explicitly, pass `-DCMAKE_CUDA_ARCHITECTURES=89` (Ada),
+for example, or a quoted list such as `-DCMAKE_CUDA_ARCHITECTURES="80;89"`.
+
CUDA extensions use sd.cpp's `thirdparty/cutlass` submodule by default
for eligible INT8 GEMM and CuTe attention operations. If its headers are missing,
CMake stops with an initialization hint; it does not download them automatically.
@@ -152,21 +138,83 @@ the old bundled path becomes `thirdparty/cutlass`, while custom paths and an
empty disabled value are preserved. An explicitly set `SD_CUDA_CUTLASS_PATH`
takes precedence. Non-CUDA builds do not require CUTLASS.
-## Build with HipBLAS
+## Build with HIPBLAS
+
+Use `-DSD_HIPBLAS=ON` for AMD GPU acceleration through HIP and hipBLAS.
+Install a compatible AMD GPU driver and the ROCm SDK, including the HIP compiler,
+hipBLAS, rocBLAS, and their development files. See
+[AMD's ROCm installation guide](https://rocm.docs.amd.com/en/latest/install/rocm.html)
+for supported GPUs, operating systems, and installation methods.
+
+When the hipBLASLt development package (version 1.0 or later) is available,
+CMake also enables INT8 GEMM tuning. The first run of an eligible matrix shape
+benchmarks the no-workspace candidates returned by hipBLASLt for the current
+device, including CDNA devices, and caches the result in the process. It
+selects a hipBLASLt candidate that runs successfully and beats hipBLAS, or a
+working candidate if hipBLAS does not support the operation.
+Set `SD_HIP_DISABLE_I8_LT=1` to use the hipBLAS GEMM path for comparison.
+
+With a compiled wave32 WMMA kernel, the HIP flash attention path supports
+head dimensions 40, 52, 64, 72, 80, 120, 128, 160, 256, and 320, including
+grouped-query attention. It requires unmasked attention with at least 512
+query tokens and 512 key tokens. Set `SD_HIP_DISABLE_WMMA_ATTN=1` to use
+ggml's native attention path for comparison.
-This provides GPU acceleration using AMD GPU. Make sure to have the ROCm toolkit installed.
-To build for another GPU architecture than installed in your system, set `$GFX_NAME` manually to the desired architecture (replace first command). This is also necessary if your GPU is not officially supported by ROCm, for example you have to set `$GFX_NAME` manually to `gfx1030` for consumer RDNA2 cards.
+**Linux**
-Windows User Refer to [docs/hipBLAS_on_Windows.md](docs%2FhipBLAS_on_Windows.md) for a comprehensive guide.
+With ROCm installed, use the default CMake generator and host compilers:
```shell
mkdir build && cd build
-if command -v rocminfo; then export GFX_NAME=$(rocminfo | awk '/ *Name: +gfx[1-9]/ {print $2; exit}'); else echo "rocminfo missing!"; fi
-if [ -z "${GFX_NAME}" ]; then echo "Error: Couldn't detect GPU!"; else echo "Building for GPU: ${GFX_NAME}"; fi
-cmake .. -G "Ninja" -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DSD_HIPBLAS=ON -DCMAKE_BUILD_TYPE=Release -DGPU_TARGETS=$GFX_NAME -DAMDGPU_TARGETS=$GFX_NAME -DCMAKE_BUILD_WITH_INSTALL_RPATH=ON -DCMAKE_POSITION_INDEPENDENT_CODE=ON
+cmake .. -DSD_HIPBLAS=ON
cmake --build . --config Release
```
+For an SDK outside the default installation path, set `ROCM_PATH` to its root
+and add `$ROCM_PATH/bin` to `PATH` before configuring. If its shared libraries
+are not on the system library search path, add `$ROCM_PATH/lib` and
+`$ROCM_PATH/lib64` to `LD_LIBRARY_PATH` when running the executable.
+
+**Windows**
+
+Follow the Windows environment setup in [Ninja](#ninja). The Windows HIP build
+requires ROCm Clang with Ninja; the Visual Studio generator is not supported.
+
+Set `HIP_PATH` to the SDK root. The HIP SDK installer normally sets this variable;
+for [ROCm wheels](https://github.com/ROCm/TheRock/blob/main/RELEASES.md), run
+`rocm-sdk init` and use `rocm-sdk path --root`. The build commands below cover
+both the installer and wheel SDK compiler layouts.
+
+For the wheel SDK, also set the device library path before building:
+
+```powershell
+$env:HIP_DEVICE_LIB_PATH = "$env:HIP_PATH\lib\llvm\amdgcn\bitcode"
+```
+
+Then configure and build:
+
+```powershell
+$env:ROCM_PATH = $env:HIP_PATH
+$env:PATH = "$env:HIP_PATH\bin;$env:HIP_PATH\lib\llvm\bin;$env:PATH"
+cmake -S . -B build-hip -G Ninja -DSD_HIPBLAS=ON -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=Release
+cmake --build build-hip --config Release
+```
+
+Keep the SDK's `bin` directory on `PATH` when running `build-hip\bin\sd-cli.exe`
+so its runtime DLLs can be found.
+
+**GPU targets and verification**
+
+CMake normally detects the installed GPU. To select a target explicitly or build
+on a machine without an AMD GPU, add `-DGPU_TARGETS=gfx1100` to the configure
+command (for example, for an RX 7900 XTX, XT, or GRE). For multiple targets, use a
+quoted list such as `-DGPU_TARGETS="gfx1100;gfx1200"`. Check AMD's
+[GPU specifications](https://rocm.docs.amd.com/en/latest/reference/gpu-specs.html)
+for the correct target; the installed SDK libraries must also support it.
+
+Use a fresh build directory when switching SDKs or compilers. Run the resulting
+`sd-cli --version` to check that the executable starts without loading a model.
+
## Build with MUSA
This provides GPU acceleration using Moore Threads GPUs. The configuration below follows upstream validation with MUSA SDK 5.2.0 and MTT S5000 (PH1, `mp_31`). Install that toolkit before building. Older SDKs such as 4.2 may lack the CUB headers required by the current backend.
@@ -210,10 +258,8 @@ Currently, it supports only Adreno GPUs and is primarily optimized for Q4_0 type
To build for Windows ARM please refers to [Windows 11 Arm64](https://github.com/ggml-org/llama.cpp/blob/master/docs/backend/OPENCL.md#windows-11-arm64)
-Building for Android:
-
- Android NDK:
- Download and install the Android NDK from the [official Android developer site](https://developer.android.com/ndk/downloads).
+For Android, prepare [Ninja](#ninja) and install the Android NDK from the
+[official Android developer site](https://developer.android.com/ndk/downloads).
Setup OpenCL Dependencies for NDK:
@@ -245,7 +291,7 @@ You need to provide OpenCL headers and the ICD loader library to your NDK sysroo
-DANDROID_PLATFORM=24 \
-DANDROID_STL=c++_shared
- ninja
+ cmake --build .
# Replace
-
-
-
diff --git a/docs/backend_probe.md b/docs/development/backend_probe.md
similarity index 100%
rename from docs/backend_probe.md
rename to docs/development/backend_probe.md
diff --git a/docs/development/c_api.md b/docs/development/c_api.md
new file mode 100644
index 0000000000..58587a6fac
--- /dev/null
+++ b/docs/development/c_api.md
@@ -0,0 +1,63 @@
+# C API Internals
+
+The public declarations live in [stable-diffusion.h](../../include/stable-diffusion.h).
+See the [C API guide](../guides/c_api.md) for keys, value types and ownership rules.
+
+## Internal modules
+
+| Module | Responsibility |
+| --- | --- |
+| `src/api/options.h/.cpp` | Opaque options, key registration, setter validation and conversion to typed configuration. |
+| `src/config.h/.cpp` | Typed configuration and the library defaults for each configuration group. |
+| `src/api/tensor.h/.cpp` | Opaque tensor handles backed by `sd::Tensor
-
-### ERNIE-Image
-
-```
-.\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
-```
-
-
diff --git a/docs/esrgan.md b/docs/esrgan.md
deleted file mode 100644
index 4068ef11c7..0000000000
--- a/docs/esrgan.md
+++ /dev/null
@@ -1,13 +0,0 @@
-## Using ESRGAN to upscale results
-
-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.
-
-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.
-
-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.
-
-- Specify the model path using the `--upscale-model PATH` parameter. example:
-
-```bash
-sd-cli -m ../models/v1-5-pruned-emaonly.safetensors -p "a lovely cat" --upscale-model ../models/RealESRGAN_x4plus_anime_6B.pth
-```
diff --git a/docs/fibo2.md b/docs/fibo2.md
deleted file mode 100644
index 064d800892..0000000000
--- a/docs/fibo2.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# How to Use
-
-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
-
-- 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
-
-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](./int8_convrot.md) for backend requirements.
-
-## Examples
-
-### Fibo 2.0 Dev
-
-Dev supports both text-to-image generation and reference-image editing.
-
-```
-.\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
-```
-
-
-
-```
-.\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
-```
-
-
-
-### Fibo 2.0 Edit Turbo
-
-Edit Turbo is distilled for reference-image editing in 4 steps with CFG 1.
-
-```
-.\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
-```
-
-The BF16 files accept the same options. Use dimensions divisible by 16. Repeat `-r` to use multiple reference images; instructions can refer to `
-
-## Flux.2 klein 4B / Flux.2 klein base 4B
-
-### Download weights
-
-- 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
-
-### Examples
-
-```
-.\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
-```
-
-
-
-```
-.\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
-```
-
-
-
-```
-.\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
-```
-
-
-
-## Flux.2 klein 9B / Flux.2 klein base 9B
-
-### Download weights
-
-- 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
-
-### Examples
-
-```
-.\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
-```
-
-
-
-```
-.\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
-```
-
-
-
-```
-.\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
-```
-
-
\ No newline at end of file
diff --git a/docs/flux3.md b/docs/flux3.md
deleted file mode 100644
index 8bc0b2ec29..0000000000
--- a/docs/flux3.md
+++ /dev/null
@@ -1,50 +0,0 @@
-# How to Use
-
-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
-
-Use the root `model.safetensors` for the diffusion model.
-
-## Examples
-
-### FLUX.3 Image Klein
-
-The distilled model uses 16 steps and CFG 1.0.
-
-```
-.\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
-```
-
-
-
-```
-.\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
-```
-
-
-
-Repeat `-r` to use multiple reference images, up to 10. See [Image Editing](./edit.md) for reference-image preprocessing options.
-
-### FLUX.3 Image Klein Base
-
-```
-.\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
-```
-
-
-
-The default discrete scheduler uses the upstream time shift of 6.93 for both models. Use `--flow-shift` to override it.
diff --git a/docs/backend.md b/docs/guides/backend.md
similarity index 98%
rename from docs/backend.md
rename to docs/guides/backend.md
index cc6545da92..f7edddf592 100644
--- a/docs/backend.md
+++ b/docs/guides/backend.md
@@ -273,8 +273,8 @@ flags are deprecated and emit a warning, but remain supported when
`--conv-direct` is omitted. Use `--conv-direct auto,diffusion=on,controlnet=on`
and `--conv-direct auto,vae=on`, respectively. An explicit
`--conv-direct` takes precedence over both legacy flags regardless of order.
-Library callers can set the appended `sd_ctx_params_t::conv_direct_mode` field
-to the same string; null or empty selects `auto` while honoring legacy true
+Library callers can set the `conv_direct_mode` context-option key with
+`sd_opt_set_string()` to the same string; unset or empty selects `auto` while honoring legacy true
flags. The context copies the string.
## Flash attention (`--flash-attn on|off|auto`)
@@ -339,9 +339,10 @@ row-split configurations, which can fall back to layer split during initializati
Use `--flash-attn on` and `--flash-attn off,diffusion=on`, respectively.
Both aliases write the same mode string as `--flash-attn`; the last occurrence
of any of these options wins. Library callers
-can set `sd_ctx_params_t::flash_attn_mode` to the same string, including
+can set the `flash_attn_mode` context-option key with `sd_opt_set_string()`
+to the same string, including
`"on"`, `"off"`, `"auto"`, or `"auto,te=off,vae=on"`.
-A null or empty string uses automatic selection unless a
+An unset or empty string uses automatic selection unless a
legacy `flash_attn` or `diffusion_flash_attn` boolean is set. The context copies
the string; no new enum is required.
diff --git a/docs/guides/c_api.md b/docs/guides/c_api.md
new file mode 100644
index 0000000000..055056d57e
--- /dev/null
+++ b/docs/guides/c_api.md
@@ -0,0 +1,507 @@
+# C API
+
+Use purpose-specific opaque options for model loading, generation and
+postprocessing, and
+opaque `sd_result_t` objects to read generated outputs. The library allocates and
+frees these objects; applications must not allocate them by size or access fields.
+
+## Loading and generation
+
+This C example loads a checkpoint and generates an image. Check every setter:
+an unsuccessful setter preserves the previous value, including its unset state.
+
+```c
+#include
-
diff --git a/docs/hipBLAS_on_Windows.md b/docs/hipBLAS_on_Windows.md
deleted file mode 100644
index cd8465721b..0000000000
--- a/docs/hipBLAS_on_Windows.md
+++ /dev/null
@@ -1,88 +0,0 @@
-# Using hipBLAS on Windows
-
-To get hipBLAS in `stable-diffusion.cpp` working on Windows, go through this guide section by section.
-
-## Build Tools for Visual Studio 2022
-
-Skip this step if you already have Build Tools installed.
-
-To install Build Tools, go to [Visual Studio Downloads](https://visualstudio.microsoft.com/vs/), download `Visual Studio 2022 and other Products` and run the installer.
-
-## CMake
-
-Skip this step if you already have CMake installed: running `cmake --version` should output `cmake version x.y.z`.
-
-Download latest `Windows x64 Installer` from [Download | CMake](https://cmake.org/download/) and run it.
-
-## ROCm
-
-Skip this step if you already have Build Tools installed.
-
-The [validation tools](https://rocm.docs.amd.com/en/latest/reference/validation_tools.html) not support on Windows. So you should confirm the Version of `ROCM` by yourself.
-
-Fortunately, `AMD` provides complete help documentation, you can use the help documentation to install [ROCM](https://rocm.docs.amd.com/en/latest/deploy/windows/quick_start.html)
-
->**If you encounter an error, if it is [AMD ROCm Windows Installation Error 215](https://github.com/RadeonOpenCompute/ROCm/issues/2363), don't worry about this error. ROCM has been installed correctly, but the vs studio plugin installation failed, we can ignore it.**
-
-Then we must set `ROCM` as environment variables before running cmake.
-
-Usually if you install according to the official tutorial and do not modify the ROCM path, then there is a high probability that it is here `C:\Program Files\AMD\ROCm\7.1.1\bin`
-
-This is what I use to set the clang:
-```Commandline
-set CC=C:\Program Files\AMD\ROCm\7.1.1\bin\clang.exe
-set CXX=C:\Program Files\AMD\ROCm\7.1.1\bin\clang++.exe
-```
-
-## Ninja
-
-Skip this step if you already have Ninja installed: running `ninja --version` should output `1.11.1`.
-
-Download latest `ninja-win.zip` from [GitHub Releases Page](https://github.com/ninja-build/ninja/releases/tag/v1.11.1) and unzip. Then set as environment variables. I unzipped it in `C:\Program Files\ninja`, so I set it like this:
-
-```Commandline
-set ninja=C:\Program Files\ninja\ninja.exe
-```
-## Building stable-diffusion.cpp
-
-The thing different from the regular CPU build is `-DSD_HIPBLAS=ON` ,
-`-G "Ninja"`, `-DCMAKE_C_COMPILER=clang`, `-DCMAKE_CXX_COMPILER=clang++`, `-DAMDGPU_TARGETS=gfx1150;gfx1151;gfx1200;gfx1201;gfx1100;gfx1101;gfx1102;gfx1030;gfx1031;gfx1032`
-
->**Notice**: check the `clang` and `clang++` information:
-```Commandline
-clang --version
-clang++ --version
-```
-
-If you see like this, we can continue:
-```
-clang version 17.0.0 (git@github.amd.com:Compute-Mirrors/llvm-project e3201662d21c48894f2156d302276eb1cf47c7be)
-Target: x86_64-pc-windows-msvc
-Thread model: posix
-InstalledDir: C:\Program Files\AMD\ROCm\7.1.1\bin
-```
-
-```
-clang version 17.0.0 (git@github.amd.com:Compute-Mirrors/llvm-project e3201662d21c48894f2156d302276eb1cf47c7be)
-Target: x86_64-pc-windows-msvc
-Thread model: posix
-InstalledDir: C:\Program Files\AMD\ROCm\7.1.1\bin
-```
-
->**Notice** that the GPU targets are now compatible with multiple GPU architectures (ROCm 7.1.1 targets). You can change them to match your GPU architecture. Click here to see your architecture [LLVM Target](https://rocm.docs.amd.com/en/latest/release/windows_support.html#windows-supported-gpus)
-
-Examples:
-- AMD Radeon™ RX 7900 XTX Graphics: `gfx1100`
-- AMD Radeon™ RX 7900 XT Graphics: `gfx1101`
-- AMD Radeon™ RX 7900 GRE Graphics: `gfx1102`
-
-option:
-
-```commandline
-mkdir build
-cd build
-cmake .. -G "Ninja" -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DSD_HIPBLAS=ON -DCMAKE_BUILD_TYPE=Release -DAMDGPU_TARGETS="gfx1150;gfx1151;gfx1200;gfx1201;gfx1100;gfx1101;gfx1102;gfx1030;gfx1031;gfx1032"
-cmake --build . --config Release
-```
-
-If everything went OK, `build\bin\sd-cli.exe` file should appear.
diff --git a/docs/hunyuan_video.md b/docs/hunyuan_video.md
deleted file mode 100644
index fadb884ef4..0000000000
--- a/docs/hunyuan_video.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# HunyuanVideo 1.5
-
-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
-
-- 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
-
-## Text-to-video example
-
-```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
-```
-
-
\ No newline at end of file
diff --git a/docs/ideogram4.md b/docs/ideogram4.md
deleted file mode 100644
index f0f1dd2500..0000000000
--- a/docs/ideogram4.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# How to Use
-
-## Download weights
-
-- 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
-
-## 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
-weights directly cast only the active layer to a temporary BF16 tensor during
-execution; the loader does not expand the entire checkpoint to BF16.
-
-With `SD_USE_UPSTREAM_GGML=ON`, FP8 tensors are converted to F16 at load time
-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
-
-The following conversion is only needed when creating a quantized GGUF model.
-
-fp8 scale -> bf16
-
-```
-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
-
-```
-.\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
-```
-
-If you want lower VRAM usage, you can change the quantization from q8_0 to a lower-level quantization, such as q4_0.
-
-
-## Examples
-
-```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
-```
-
-
diff --git a/docs/ip_adapter.md b/docs/ip_adapter.md
deleted file mode 100644
index 27f9ae6896..0000000000
--- a/docs/ip_adapter.md
+++ /dev/null
@@ -1,87 +0,0 @@
-# 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
-
-## Notes
-
-- 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/kontext.md b/docs/kontext.md
deleted file mode 100644
index 46da3c3994..0000000000
--- a/docs/kontext.md
+++ /dev/null
@@ -1,39 +0,0 @@
-# How to Use
-
-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
-
-- 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
-
-## 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.
-
-```
-.\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
-```
-
-## Run
-
-- `--cfg-scale` is recommended to be set to 1.
-
-### 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
-```
-
-
-| ref_image | prompt | output |
-| ---- | ---- |---- |
-|  | change 'flux.cpp' to 'kontext.cpp' | |
-
-
-
diff --git a/docs/krea2.md b/docs/krea2.md
deleted file mode 100644
index 67fad023ed..0000000000
--- a/docs/krea2.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# How to Use
-
-Krea2 uses a Krea2 diffusion transformer, the Wan2.1 VAE, and Qwen3-VL 4B as the LLM text encoder.
-
-## Download weights
-
-- 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
-
-## Examples
-
-### Krea2
-
-```
-.\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
-```
-
-
diff --git a/docs/lcm.md b/docs/lcm.md
deleted file mode 100644
index 3a11938aad..0000000000
--- a/docs/lcm.md
+++ /dev/null
@@ -1,15 +0,0 @@
-## LCM/LCM-LoRA
-
-- Download LCM-LoRA form https://huggingface.co/latent-consistency/lcm-lora-sdv1-5
-- Specify LCM-LoRA by adding `
-
-### Lens Turbo
-
-```
-.\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
-```
-
-
diff --git a/docs/lingbot_video.md b/docs/lingbot_video.md
deleted file mode 100644
index b92165ab5f..0000000000
--- a/docs/lingbot_video.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# How to Use
-
-Lingbot Video uses a Lingbot diffusion transformer, the Wan2.1 VAE, and Qwen3-VL 4B as the LLM text encoder.
-
-## Download weights
-
-- 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
-
-## Notes
-
-- Use `-M vid_gen`.
-- T2V uses the text prompt only.
-- I2V uses `-i` as the first video frame. The same image is also passed to the
- 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/llada_image.md b/docs/llada_image.md
deleted file mode 100644
index d939e78cea..0000000000
--- a/docs/llada_image.md
+++ /dev/null
@@ -1,155 +0,0 @@
-# How to Use
-
-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.
-
-## Download weights
-
-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.
-
-The two published checkpoints are **not** interchangeable. LLaDA-Image-Turbo and LLaDA-Image
-ship different transformers, text encoders, QueryFormers and text projections; only the VAE,
-the SigVQ encoder and the tokenizer are shared. Mixing the two produces degraded output rather
-than a clean error, so keep each checkpoint's files together.
-
-Both need an external LLaDA2 `tokenizer.json`, which is not embedded in sd.cpp and is the same
-file for either checkpoint. Take `tokenizer/tokenizer.json` from either repository and pass it
-with `--tokenizer`. See [JSON tokenizers](tokenizers.md) for CLI and C API usage.
-
-### LLaDA-Image-Turbo (4 steps)
-
-Converted transformer, text encoder and pre-merged connectors are at
-https://huggingface.co/fszontagh/LLaDA-Image-Turbo-GGUF:
-
-- `llada-image-turbo-f16.gguf`
-- `llada-image-turbo-text_encoder-q8_0.gguf`
-- `llada-image-turbo-connectors.safetensors` for text to image, or
- `llada-image-turbo-connectors-edit.safetensors`, which also carries the SigVQ encoder that
- editing needs.
-
-Other quantizations of the transformer and the text encoder are in the same repository.
-
-The VAE comes from the original repository,
-https://huggingface.co/inclusionAI/LLaDA-Image-Turbo: `vae/diffusion_pytorch_model.safetensors`,
-referred to below as `llada_vae.safetensors`.
-
-### LLaDA-Image (50 steps)
-
-Converted transformer, text encoder and pre-merged connectors are at
-https://huggingface.co/fszontagh/LLaDA-Image-GGUF:
-
-- `llada-image-f16.gguf`
-- `llada-image-text_encoder-q8_0.gguf`
-- `llada-image-connectors.safetensors` for text to image, or
- `llada-image-connectors-edit.safetensors`, which also carries the SigVQ encoder that editing
- needs.
-
-Other quantizations of the transformer and the text encoder are in the same repository.
-
-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
-
-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
-```
-
-### 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
-tensor name prefixed with its component name. Leaving `sigvq` out skips loading the 2.6 GB
-encoder:
-
-```python
-from safetensors.torch import load_file, save_file
-
-merged = {}
-for prefix, path in [
- ("queryformer", "queryformer/diffusion_pytorch_model.safetensors"),
- ("text_projection", "text_projection/diffusion_pytorch_model.safetensors"),
- ("sigvq", "sigvq/diffusion_pytorch_model.safetensors"),
-]:
- for name, tensor in load_file(path).items():
- merged[f"{prefix}.{name}"] = tensor
-save_file(merged, "llada_connectors.safetensors")
-```
-
-## Examples
-
-### Text to image
-
-```bash
-./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 \
- --prompt "a lovely cat holding a sign says 'llada.cpp'" \
- --width 1024 \
- --height 1024 \
- --steps 4 \
- --cfg-scale 1.0 \
- --seed 42 \
- --output output.png
-```
-
-
-
-### Image editing
-
-```bash
-./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 \
- --prompt "change the sign text to 'sd.cpp'" \
- --width 1024 \
- --height 1024 \
- --steps 4 \
- --cfg-scale 1.0 \
- --output output.png
-```
-
-
-
-See [edit.md](./edit.md) for the shared reference-image options. LLaDA-Image uses the
-`llada_image` preset by default, resizing the reference image to the output width and height
-before VAE encoding. SigVQ uses bilinear resizing to half the output resolution and inputs
-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
-
-- 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
- `--steps 50 --cfg-scale 5`.
-- Width and height are rounded up to a multiple of 16. For editing the reference pipeline
- requires them to be divisible by 32.
-- Edit the 50-step base model at 1024x1024. At 512x512 it returns the reference image almost
- unchanged instead of applying the instruction; LLaDA-Image-Turbo edits correctly at both.
-- Editing runs the reference and the target in one sequence, so it needs roughly twice the
- tokens of text to image at the same size. On 12 GB, editing at 1024x1024 needs
- flash attention; without it the diffusion graph does not fit.
-- The weights total about 16 GB, but segmented execution streams them, so a much smaller
- budget works. At 512x512, `--max-vram 6` costs almost nothing over unconstrained execution,
- and `--max-vram 3` still produces byte-identical output at roughly 2.5x the time.
-- `--scheduler` defaults to `llada_image`, which reproduces the reference Kumaraswamy sigma
- grid. `--extra-sample-args uniform=1` selects the uniform grid instead.
-- Prompt templating is handled automatically; pass a plain description.
-- VQ-conditioned generation (`generation_mode="vq"`, where the text encoder decodes image
- tokens before diffusion) is not implemented.
diff --git a/docs/longcat_image.md b/docs/longcat_image.md
deleted file mode 100644
index ae730b4727..0000000000
--- a/docs/longcat_image.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# How to Use
-
-LongCat-Image uses a LongCat diffusion transformer, the FLUX VAE, and Qwen2.5-VL as the LLM text encoder.
-
-## Download weights
-
-- 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`.
-
-## Run
-
-LongCat uses quoted text for character-level text rendering. Put target text inside single quotes, double quotes, or Chinese quotes.
-
-### LongCat Image
-
-```
-.\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
-```
-
-
diff --git a/docs/lora.md b/docs/lora.md
deleted file mode 100644
index d6dc718991..0000000000
--- a/docs/lora.md
+++ /dev/null
@@ -1,26 +0,0 @@
-## 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 is specified via prompt, just like [stable-diffusion-webui](https://github.com/AUTOMATIC1111/stable-diffusion-webui/wiki/Features#lora).
-
-Here's a simple example:
-
-```
-./bin/sd-cli -m ../models/v1-5-pruned-emaonly.safetensors -p "a lovely cat
-
-## 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
-```
-
-
diff --git a/docs/ming_image.md b/docs/ming_image.md
deleted file mode 100644
index c242559212..0000000000
--- a/docs/ming_image.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# Ming-Image
-
-[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
-
-- 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
-
-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](int8_convrot.md). Use the BF16 text encoder.
-
-## 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
-```
diff --git a/docs/minimax_h3.md b/docs/minimax_h3.md
deleted file mode 100644
index 6b672ba99f..0000000000
--- a/docs/minimax_h3.md
+++ /dev/null
@@ -1,204 +0,0 @@
-# MiniMax-H3
-
-MiniMax-H3 jointly generates video and stereo audio with a packed diffusion
-transformer. The implementation supports text-to-audio-video (T2VA), optional
-first-frame conditioning (I2VA), first/last-frame conditioning (FL2VA), and
-image/video/audio reference conditioning (Ref2VA).
-
-## Model files
-
-Pass the four MiniMax-H3 components separately:
-
-- `--diffusion-model`: MiniMax-H3 diffusion transformer
-- `--vae`: MiniMax-H3 video VAE
-- `--audio-vae`: MiniMax-H3 audio VAE
-- `--llm`: the MiniMax-H3 Qwen3-VL-32B text encoder checkpoint
-
-The text encoder must be the MiniMax-H3 variant: Qwen3-VL-32B truncated to 50
-language layers and exported without the final language-model normalization.
-Its Qwen3-VL vision tower, including the three DeepStack mergers, must also be
-present. If the vision tower is stored separately, pass it with `--llm_vision`.
-
-Both the original time-embedder DiT and the smaller AdaLN curve-table variant
-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
-- 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
-
-```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
-```
-
-
-
-Omitting `--audio-vae` still runs the joint diffusion model but produces video without a
-decoded audio track.
-
-## First/last-frame conditioning
-
-Add `--init-img` for I2VA, or both `--init-img` and `--end-img` for FL2VA:
-
-```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
-```
-
-
-
-## Reference-to-audio-video conditioning
-
-Ref2VA accepts any combination of reference images, reference videos, paired
-video soundtracks, and standalone audio references:
-
-```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
diff --git a/docs/models/animatediff.md b/docs/models/animatediff.md
new file mode 100644
index 0000000000..ef110febcc
--- /dev/null
+++ b/docs/models/animatediff.md
@@ -0,0 +1,341 @@
+# AnimateDiff
+
+AnimateDiff adds video generation to an SD 1.5 checkpoint using a compatible motion module.
+
+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
+ - original checkpoint: https://huggingface.co/guoyww/animatediff/resolve/main/v3_sd15_mm.ckpt
+- SD 1.5 base model
+ - any SD 1.5 checkpoint works. `realisticVisionV60B1` and `toonyou_beta3`
+ are the ones used in guoyww's reference configs.
+- Domain Adapter LoRA (optional, v3 only, sharpens the base UNet's output
+ toward the motion module's trained distribution)
+ - ckpt: https://huggingface.co/guoyww/animatediff/resolve/main/v3_sd15_adapter.ckpt
+ - place under your `--lora-model-dir` and reference in the prompt as
+ `
|
+| Close-up rabbit macro shot |
|
+| Coastline, storm, waves, lightning |
|
+| Old house, storm, forest, night |
|
+
+##### v2 (384x384, `mm_sd_v15_v2.ckpt`)
+
+| Prompt | Sample |
+|---------------------------------------|--------|
+| B&W man on stormy coastline |
|
+| Close-up rabbit macro shot |
|
+| Coastline, storm, waves, lightning |
|
+| Old house, storm, forest, night |
|
+
+Motion is strong for scenes with motion cues in the prompt (storm/waves/wind)
+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
+
+Attaching the `v3_sd15_adapter` LoRA sharpens the base UNet output toward
+the training distribution the motion module was fine-tuned against. Same
+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 ...
+
+**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
+```
+
+**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 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
+ motion arc. Frame counts up to 32 are supported by the positional encoding
+ but exceed the trained regime and produce more static output.
+- At `--video-frames 1` the motion module is skipped entirely and the output
+ is bit-identical to `-M img_gen`. This avoids the single-token
+ temporal-attention degeneracy that would otherwise emit an untrained-magnitude
+ residual on a single-frame sample.
+- The base UNet is frozen, so character identity and style follow the SD 1.5
+ checkpoint you pass to `--model`. LoRAs and prompt weighting attach to the
+ base model in the usual way.
+- No mid_block motion module in v3. `mm_sdxl_v10_beta` (SDXL variant) is not
+ supported yet.
+- Output is written as MJPEG AVI. Use `--fps` to set playback speed.
diff --git a/docs/models/boogu_image.md b/docs/models/boogu_image.md
new file mode 100644
index 0000000000..d7d133cd3f
--- /dev/null
+++ b/docs/models/boogu_image.md
@@ -0,0 +1,93 @@
+# Boogu Image
+
+Boogu Image uses a Boogu diffusion transformer, the FLUX VAE, and Qwen3-VL as the LLM text and vision encoder.
+
+## Model files
+
+| 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)
+
+#### 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
+```
+
+**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
+```
+
+
diff --git a/docs/models/chroma.md b/docs/models/chroma.md
new file mode 100644
index 0000000000..51c9685981
--- /dev/null
+++ b/docs/models/chroma.md
@@ -0,0 +1,101 @@
+# 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.
+
+## 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)
diff --git a/docs/models/distilled_sd.md b/docs/models/distilled_sd.md
new file mode 100644
index 0000000000..30e75aa4bc
--- /dev/null
+++ b/docs/models/distilled_sd.md
@@ -0,0 +1,202 @@
+# Distilled Stable Diffusion models
+
+This guide covers SSD-1B, Vega, Tiny SD/SD2, and SDXS checkpoints. Choose the
+base-model family and preparation steps matching the checkpoint.
+
+## Model files
+
+| 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:
+
+ * https://huggingface.co/segmind/SSD-1B/resolve/main/SSD-1B-A1111.safetensors
+ * https://huggingface.co/hassenhamdi/SSD-1B-fp8_e4m3fn/resolve/main/SSD-1B_fp8_e4m3fn.safetensors
+
+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
+
+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.
+
+### 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
+
+NotaAI provides the following model online:
+
+* https://huggingface.co/nota-ai/bk-sdm-v2-tiny
+
+Creating a .safetensors file involves two steps. First, run this short Python script to download the model from Hugging Face:
+
+```python
+from diffusers import StableDiffusionPipeline
+pipe = StableDiffusionPipeline.from_pretrained("nota-ai/bk-sdm-v2-tiny",cache_dir="./")
+```
+
+Second, create the .safetensors file by running:
+
+**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
+
+Several Tiny SD 1.x models are available online, such as:
+
+ * https://huggingface.co/segmind/tiny-sd
+ * https://huggingface.co/segmind/portrait-finetuned
+ * 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 the model using Python on your computer, for example this way:
+
+```python
+import torch
+from diffusers import StableDiffusionPipeline
+pipe = StableDiffusionPipeline.from_pretrained("segmind/tiny-sd")
+unet=pipe.unet
+for param in unet.parameters():
+ param.data = param.data.contiguous() # <- important here
+pipe.save_pretrained("segmindtiny-sd", safe_serialization=True)
+```
+
+Run the conversion script:
+
+**Windows (PowerShell)**
+
+```powershell
+python convert_diffusers_to_original_stable_diffusion.py --model_path .\segmindtiny-sd --checkpoint_path .\segmind_tiny-sd.safetensors --half --use_safetensors
+```
+
+**Linux/macOS**
+
+```sh
+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.
+
+### 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:
+
+* https://huggingface.co/akleine/sdxs-512
+* https://huggingface.co/concedo/sdxs-512-tinySDdistilled-GGUF
+
+### 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:
+
+* https://huggingface.co/akleine/sdxs-09
+
+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
new file mode 100644
index 0000000000..e4e30698af
--- /dev/null
+++ b/docs/models/ernie_image.md
@@ -0,0 +1,99 @@
+# 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.
+
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| ERNIE-Image-Turbo | [Safetensors](https://huggingface.co/Comfy-Org/ERNIE-Image/tree/main/diffusion_models)
+
+#### 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
+```
+
+**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
+```
+
+
diff --git a/docs/models/esrgan.md b/docs/models/esrgan.md
new file mode 100644
index 0000000000..3d1a589e28
--- /dev/null
+++ b/docs/models/esrgan.md
@@ -0,0 +1,42 @@
+# ESRGAN and MoSR
+
+ESRGAN and compatible MoSR weights upscale generated images. Pass the chosen
+upscaler with `--upscale-model`.
+
+## Model files
+
+| 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 |
+
+## Usage
+
+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
new file mode 100644
index 0000000000..4919bda126
--- /dev/null
+++ b/docs/models/fibo2.md
@@ -0,0 +1,154 @@
+# 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.
+
+## Model files
+
+| 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)
+
+**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
+```
+
+**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
+```
+
+
+
+#### 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
+```
+
+**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 `
+
+#### Flux.2 klein 4B / Flux.2 klein base 4B
+
+**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 `
+ -p "a lovely cat" `
+ --cfg-scale 1.0 `
+ --steps 4 `
+ --offload-to-cpu `
+ -v
+```
+
+**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 \
+ -p "a lovely cat" \
+ --cfg-scale 1.0 \
+ --steps 4 \
+ --offload-to-cpu \
+ -v
+```
+
+
+
+**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
+```
+
+**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
+```
+
+
+
+**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
+```
+
+**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
+```
+
+
+
+#### Flux.2 klein 9B / Flux.2 klein base 9B
+
+**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 `
+ -p "a lovely cat" `
+ --cfg-scale 1.0 `
+ --steps 4 `
+ --offload-to-cpu `
+ -v
+```
+
+**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 \
+ -p "a lovely cat" \
+ --cfg-scale 1.0 \
+ --steps 4 \
+ --offload-to-cpu \
+ -v
+```
+
+
+
+**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
+```
+
+**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
+```
+
+
+
+**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
+```
+
+**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
+```
+
+
diff --git a/docs/models/flux3.md b/docs/models/flux3.md
new file mode 100644
index 0000000000..7591d7cd13
--- /dev/null
+++ b/docs/models/flux3.md
@@ -0,0 +1,144 @@
+# 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.
+
+## 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)
+
+**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
+```
+
+**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
+```
+
+
+
+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
+
+**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
+```
+
+**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
+```
+
+
+
+The default discrete scheduler uses the upstream time shift of 6.93 for both models. Use `--flow-shift` to override it.
diff --git a/docs/models/hidream_o1_image.md b/docs/models/hidream_o1_image.md
new file mode 100644
index 0000000000..09f7ac725f
--- /dev/null
+++ b/docs/models/hidream_o1_image.md
@@ -0,0 +1,59 @@
+# HiDream-O1-Image
+
+HiDream-O1-Image uses a bundled model checkpoint. The example below uses the Dev checkpoint.
+
+## Model files
+
+| 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 |
+
+## 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
+```
+
+**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
+```
+
+
diff --git a/docs/models/hunyuan_video.md b/docs/models/hunyuan_video.md
new file mode 100644
index 0000000000..f31f8cfbd2
--- /dev/null
+++ b/docs/models/hunyuan_video.md
@@ -0,0 +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,
+and ByT5 Small GlyphXL for glyph-aware text conditioning.
+
+## Model files
+
+| 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)
diff --git a/docs/models/ip_adapter.md b/docs/models/ip_adapter.md
new file mode 100644
index 0000000000..854ed88d78
--- /dev/null
+++ b/docs/models/ip_adapter.md
@@ -0,0 +1,223 @@
+# IP-Adapter
+
+[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
+```
+
+**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
+```
+
+**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
+
+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
+```
+
+**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
+
+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
+```
+
+**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
+
+## 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
new file mode 100644
index 0000000000..c711f3227d
--- /dev/null
+++ b/docs/models/kontext.md
@@ -0,0 +1,108 @@
+# 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.
+
+## 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)
diff --git a/docs/models/lcm.md b/docs/models/lcm.md
new file mode 100644
index 0000000000..90330d2a6e
--- /dev/null
+++ b/docs/models/lcm.md
@@ -0,0 +1,76 @@
+# LCM and LCM-LoRA
+
+LCM checkpoints and LCM-LoRAs support generation with a small number of steps.
+The example below applies an LCM-LoRA to SD 1.5.
+
+## 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 `
+
+#### 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
+```
+
+**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
+```
+
+
diff --git a/docs/models/lingbot_video.md b/docs/models/lingbot_video.md
new file mode 100644
index 0000000000..a085c891b3
--- /dev/null
+++ b/docs/models/lingbot_video.md
@@ -0,0 +1,77 @@
+# LingBot-Video
+
+Lingbot Video uses a Lingbot diffusion transformer, the Wan2.1 VAE, and Qwen3-VL 4B as the LLM text encoder.
+
+## Model files
+
+| 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)
+
+#### 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
+```
+
+**Linux/macOS**
+
+```sh
+./bin/sd-cli \
+ --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
+```
+
+
+
+See [edit.md](../guides/edit.md) for the shared reference-image options. LLaDA-Image uses the
+`llada_image` preset by default, resizing the reference image to the output width and height
+before VAE encoding. SigVQ uses bilinear resizing to half the output resolution and inputs
+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 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
+ `--steps 50 --cfg-scale 5`.
+- Width and height are rounded up to a multiple of 16. For editing the reference pipeline
+ requires them to be divisible by 32.
+- Edit the 50-step base model at 1024x1024. At 512x512 it returns the reference image almost
+ unchanged instead of applying the instruction; LLaDA-Image-Turbo edits correctly at both.
+- Editing runs the reference and the target in one sequence, so it needs roughly twice the
+ tokens of text to image at the same size. On 12 GB, editing at 1024x1024 needs
+ flash attention; without it the diffusion graph does not fit.
+- The weights total about 16 GB, but segmented execution streams them, so a much smaller
+ budget works. At 512x512, `--max-vram 6` costs almost nothing over unconstrained execution,
+ and `--max-vram 3` still produces byte-identical output at roughly 2.5x the time.
+- `--scheduler` defaults to `llada_image`, which reproduces the reference Kumaraswamy sigma
+ grid. `--extra-sample-args uniform=1` selects the uniform grid instead.
+- Prompt templating is handled automatically; pass a plain description.
+- VQ-conditioned generation (`generation_mode="vq"`, where the text encoder decodes image
+ tokens before diffusion) is not implemented.
diff --git a/docs/models/longcat_image.md b/docs/models/longcat_image.md
new file mode 100644
index 0000000000..ec2fae131c
--- /dev/null
+++ b/docs/models/longcat_image.md
@@ -0,0 +1,70 @@
+# LongCat Image
+
+LongCat-Image uses a LongCat diffusion transformer, the FLUX VAE, and Qwen2.5-VL as the LLM text encoder.
+
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| LongCat Image | [Safetensors](https://huggingface.co/Comfy-Org/LongCat-Image/tree/main/split_files/diffusion_models)
diff --git a/docs/models/lora.md b/docs/models/lora.md
new file mode 100644
index 0000000000..56cb60b7d3
--- /dev/null
+++ b/docs/models/lora.md
@@ -0,0 +1,62 @@
+# LoRA
+
+LoRA weights adapt a compatible base model. Select a LoRA by name and strength
+using `
+
+#### 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`.
+
+**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
+```
+
+
diff --git a/docs/models/ming_image.md b/docs/models/ming_image.md
new file mode 100644
index 0000000000..53dc7a96e6
--- /dev/null
+++ b/docs/models/ming_image.md
@@ -0,0 +1,77 @@
+# Ming-Image
+
+[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.
+
+## Model files
+
+| 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.
+
+## 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.
+
+**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
new file mode 100644
index 0000000000..862b04d3e9
--- /dev/null
+++ b/docs/models/minimax_h3.md
@@ -0,0 +1,458 @@
+# MiniMax-H3
+
+MiniMax-H3 jointly generates video and stereo audio with a packed diffusion
+transformer. The implementation supports text-to-audio-video (T2VA), optional
+first-frame conditioning (I2VA), first/last-frame conditioning (FL2VA), and
+image/video/audio reference conditioning (Ref2VA).
+
+## Model files
+
+Pass the four MiniMax-H3 components separately:
+
+- `--diffusion-model`: MiniMax-H3 diffusion transformer
+- `--vae`: MiniMax-H3 video VAE
+- `--audio-vae`: MiniMax-H3 audio VAE
+- `--llm`: the MiniMax-H3 Qwen3-VL-32B text encoder, or Qwen3-VL-4B with the P-H3 text connector
+
+For the 32B option, use the MiniMax-H3 variant: Qwen3-VL-32B truncated to 50
+language layers and exported without the final language-model normalization.
+
+For the smaller 4B option, pass the P-H3-Image text encoder, which bundles the
+connector, with `--llm`. Alternatively, pass Qwen3-VL-4B with `--llm` and the
+[separate P-H3 text connector](https://huggingface.co/PrunaAI/P-H3-Image/blob/main/text_connector/diffusion_pytorch_model.safetensors)
+with `--embeddings-connectors`. For example, replace the `--llm` argument in the
+commands below with either:
+
+**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:
+
+**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
+Qwen3-VL vision tower, including the three DeepStack mergers. If stored
+separately, pass it with `--llm_vision`. Keep using the MiniMax-H3 video and audio
+VAEs with either text encoder.
+
+Both the original time-embedder DiT and the smaller AdaLN curve-table variant
+are detected from their weights.
+
+### Download weights
+
+| 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)
+
+Use dimensions divisible by 16. The default discrete scheduler uses the upstream time shift of 5. Use `--flow-shift` to override it. The negative CFG branch skips DiT layer 22 (zero-based), matching the upstream pipeline.
diff --git a/docs/models/ovis_image.md b/docs/models/ovis_image.md
new file mode 100644
index 0000000000..ddf6c21579
--- /dev/null
+++ b/docs/models/ovis_image.md
@@ -0,0 +1,60 @@
+# Ovis-Image
+
+Ovis-Image generates images from text using an Ovis 2.5 encoder and the FLUX VAE.
+
+## Model files
+
+| Component | Weights and downloads | CLI option | Requirement |
+| --- | --- | --- | --- |
+| Ovis-Image-7B | [Safetensors](https://huggingface.co/Comfy-Org/Ovis-Image/tree/main/split_files/diffusion_models)
diff --git a/docs/models/p_h3_image.md b/docs/models/p_h3_image.md
new file mode 100644
index 0000000000..eed578416a
--- /dev/null
+++ b/docs/models/p_h3_image.md
@@ -0,0 +1,147 @@
+# 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.
+
+## Model files
+
+| 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)
+
+After:
+
+
+## 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
+ checkpoint alone does not identify the VAE format.
diff --git a/docs/models/pixart.md b/docs/models/pixart.md
new file mode 100644
index 0000000000..336e1ee272
--- /dev/null
+++ b/docs/models/pixart.md
@@ -0,0 +1,89 @@
+# 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-α.
+
+## 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)` | Path to a `.pulidembd` binary produced by the precompute tool. |
+| `--pulid-id-weight
+ ` | Path to a `.pulidembd` binary produced by the precompute tool. |
-| `--pulid-id-weight
-
[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)
[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 (`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
+```
+
+
diff --git a/docs/models/qwen_image_2.1.md b/docs/models/qwen_image_2.1.md
new file mode 100644
index 0000000000..7ddfda5a2d
--- /dev/null
+++ b/docs/models/qwen_image_2.1.md
@@ -0,0 +1,201 @@
+# 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.
+
+## Model files
+
+| 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)
[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)
[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`. | `--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).
+
+## 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 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 `
+ --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
+```
+
+
+
+To use GGUF diffusion weights, set `--diffusion-model` to the path of a file such as `qwen_image_2.1-Q4_K.gguf`.
+
+#### 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
+```
+
+**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
+
+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 ..\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`.
+
+#### Alpha channel
+
+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:
+
+> `This is an RGBA image with transparency.
[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) | `--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)
[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
+```
+
+**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
+```
+
+
+
+#### 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
+```
+
+**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
+```
+
+
+
+#### 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
+```
+
+**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
+```
+
+
diff --git a/docs/relay_vsr.md b/docs/models/relay_vsr.md
similarity index 57%
rename from docs/relay_vsr.md
rename to docs/models/relay_vsr.md
index e35f5fdb7f..4900fa4fb8 100644
--- a/docs/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.
@@ -43,7 +74,7 @@ and use `-o output.png` (or JPEG/WebP). No FPS setting is needed for an image.
The default 16 selects reference frames 0, 15, 30, and so on, and always
includes the final frame. Every input frame appears once in the output.
- `--flash-attn auto` and `--conv-direct auto` are enabled by default. See
- [backend selection](backend.md) to choose a device or weight placement.
+ [backend selection](../guides/backend.md) to choose a device or weight placement.
- Sampler, scheduler, and step settings do not configure RelayVSR.
`--vsr-temporal-chunk-size` is a SeedVR2 option.
- Long videos require enough system memory to hold the input and output frames.
diff --git a/docs/models/sd.md b/docs/models/sd.md
new file mode 100644
index 0000000000..2d1ab53e36
--- /dev/null
+++ b/docs/models/sd.md
@@ -0,0 +1,138 @@
+# Stable Diffusion 1.x, 2.x, and SDXL
+
+Stable Diffusion 1.x, 2.x, and SDXL support text-to-image and image-to-image
+generation from single-file checkpoints.
+
+## 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/checkpoints/sd-v1-4.ckpt -p "a lovely cat"
+```
+
+#### SD 1.5
+
+**Windows (PowerShell)**
+
+```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"
+```
+
+#### 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
+```
+
+**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
+```
+
+
+
+
+## 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=
[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)
[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)
[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)
[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)
[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)
[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)
[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)
[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)
[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)
[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) | `--diffusion-model` | Match the task and variant |
+| 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) | `--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)
[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
+```
+
+**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
+```
+
+
+
+#### 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
+```
+
+**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
+```
+
+
+
+#### 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
+```
+
+**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
+```
+
+
+
+#### 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
+```
+
+**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
+```
+
+
+
+#### 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
+```
+
+**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
+```
+
+
+
+#### 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
+```
+
+**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:
+
+- Recommended settings: `--sampling-method euler --steps 20 --cfg-scale 6.0`.
+ `dpm++2m` produces heavy artifacts on S2V. 4 steps with the lightning LoRA
+ (below) is the fast option.
+- Resolutions: width and height must be multiples of 16; the examples use
+ multiples of 64. 832x480 is a fast starting point; generation cost scales
+ with pixel area.
+- `--audio` accepts a WAV file; it is downmixed to mono and resampled to 16 kHz
+ internally. Audio longer than the video is truncated, video longer than the
+ audio is padded with silence. Pick `--video-frames` to match the audio:
+ roughly `audio_seconds * 16` frames, capped at one chunk (77-81 frames,
+ ~5 s at the model's 16 fps). 33, 77 and 81 map to clean latent frame counts.
+- S2V always uses 16 fps. Other requested frame rates are automatically
+ changed to 16 with a warning, including the CLI and server video output.
+ `generate_video()` returns the actual frame rate through `fps_out`; C API
+ callers should use that value when encoding the output video.
+- One generation covers the first S2V chunk window (`--video-frames` frames).
+ Long-video chunked extend mode is not implemented yet.
+- Speed: the lightx2v lightning LoRA works with S2V at 4 steps and
+ `--cfg-scale 1.0`. Use the **low_noise** variant;
+ the high_noise variant produces artifacts on S2V:
+
+**Windows (PowerShell) arguments**
+
+```text
+--lora-model-dir ..\models\loras `
+ -p "...
+
+#### 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
[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)
[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)
[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` |
+
+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
+
+#### 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
+```
+
+**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
+```
+
+
+
+#### 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
+```
+
+**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
+```
+
+
+
+#### Comparison of Different Quantization Types
+
+| bf16 | q8_0 | q6_K | q5_0 | q4_K | q4_0 | q3_K | q2_K|
+|---|---|---|---|---|---|---|---|
+|
|
|
|
|
|
|
|
|
diff --git a/docs/models/z_image_l2p.md b/docs/models/z_image_l2p.md
new file mode 100644
index 0000000000..c572af8ca2
--- /dev/null
+++ b/docs/models/z_image_l2p.md
@@ -0,0 +1,72 @@
+# Z-Image L2P
+
+[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.
+
+## Model files
+
+| 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)
[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 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.
+
+**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/docs/moss_image.md b/docs/moss_image.md
deleted file mode 100644
index 27ab26f804..0000000000
--- a/docs/moss_image.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# How to Use
-
-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
-
-- 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
-
-Pass the external `tokenizer.json` with `--tokenizer`; Qwen3.5 uses a different vocabulary from the embedded Qwen tokenizer.
-
-## Examples
-
-### MOSS-Image Base
-
-```
-.\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
-```
-
-### MOSS-Image SFT
-
-```
-.\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
-```
-
-
-
-Use dimensions divisible by 16. The default discrete scheduler uses the upstream time shift of 5. Use `--flow-shift` to override it. The negative CFG branch skips DiT layer 22 (zero-based), matching the upstream pipeline.
diff --git a/docs/ovis_image.md b/docs/ovis_image.md
deleted file mode 100644
index c561ff54b0..0000000000
--- a/docs/ovis_image.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# How to Use
-
-## Download weights
-
-- 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
-
-## Examples
-
-```
-.\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
-```
-
-
\ No newline at end of file
diff --git a/docs/p_h3_image.md b/docs/p_h3_image.md
deleted file mode 100644
index 20de6fb202..0000000000
--- a/docs/p_h3_image.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# How to Use
-
-P-H3-Image supports text-to-image and reference-image editing. It uses a MiniMax-H3 diffusion transformer, a single-frame VAE, and Qwen3-VL-4B with a text connector. Prompt enhancement is not included.
-
-## Download weights
-
-- 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
-
-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`.
-
-Use the P-H3 image VAE; the MiniMax-H3 video VAE is not compatible. No audio VAE is needed.
-
-## Examples
-
-### Text-to-image
-
-```
-.\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
-```
-
-### Image editing
-
-```
-.\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
-
-After:
-
-
-## Notes
-
-- `-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
- checkpoint alone does not identify the VAE format.
diff --git a/docs/pixart.md b/docs/pixart.md
deleted file mode 100644
index f9386abf16..0000000000
--- a/docs/pixart.md
+++ /dev/null
@@ -1,46 +0,0 @@
-# How to Use
-
-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-α.
-- Tokenizer: the T5 vocabulary is embedded; no extra tokenizer file is needed.
-
-## Examples
-
-```
-.\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
-```
-
-## Notes
-
-- The VAE scaling factor defaults to `0.13025` for PixArt-Σ. PixArt-α
- checkpoints with resolution micro-condition weights use `0.18215`.
- PixArt-α 512 has the same tensor layout as PixArt-Σ, so it requires an
- explicit override: `--model-args "pixart_vae_scale_factor=0.18215"`.
- This argument can also override the scale for other compatible checkpoints.
-- PixArt-Σ checkpoints compute 2D sincos positional embeddings at runtime;
- the trained grid is 64x64 patches with an interpolation scale of 2.
- For checkpoints trained at a different resolution, the positional embedding
- parameters can be adjusted via model args:
- `--model-args "pixart_pos_embed_base_size=
-
-
-
diff --git a/docs/qwen_image_2.1.md b/docs/qwen_image_2.1.md
deleted file mode 100644
index 8663731465..0000000000
--- a/docs/qwen_image_2.1.md
+++ /dev/null
@@ -1,99 +0,0 @@
-# How to Use
-
-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
-
-- 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`.
-
-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
-
-Run the following commands from the build directory. Use image dimensions divisible by 32. The resolution-dependent flow schedule is selected automatically.
-
-### Text to image
-
-```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
-```
-
-
-
-To use GGUF diffusion weights, set `--diffusion-model` to the path of a file such as `qwen_image_2.1-Q4_K.gguf`.
-
-### 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:
-
-```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
-
-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`.
-
-```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
-```
-
-For multiple reference images, repeat `-r` in the desired order, for example `-r first.png -r second.png`.
-
-### Prefix cache
-
-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.
-
-### Alpha channel
-
-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:
-
-> `This is an RGBA image with transparency.
-
-
-### Qwen Image Edit 2509
-
-```
-.\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'"
-```
-
-
-
-### 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.
-
-```
-.\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
-```
-
-
diff --git a/docs/sd.md b/docs/sd.md
deleted file mode 100644
index 44a4c1f99d..0000000000
--- a/docs/sd.md
+++ /dev/null
@@ -1,37 +0,0 @@
-## Download weights
-
-- 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
-
-### txt2img example
-
-```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
-```
-
-Using formats of different precisions will yield results of varying quality.
-
-| f32 | f16 |q8_0 |q5_0 |q5_1 |q4_0 |q4_1 |
-| ---- |---- |---- |---- |---- |---- |---- |
-|  | | | | | | |
-
-### img2img example
-
-- `./output.png` is the image generated from the above txt2img pipeline
-
-
-```
-./bin/sd-cli -m ../models/sd-v1-4.ckpt -p "cat with blue eyes" -i ./output.png -o ./img2img_output.png --strength 0.4
-```
-
-
-
diff --git a/docs/taesd.md b/docs/taesd.md
deleted file mode 100644
index 8331f441bf..0000000000
--- a/docs/taesd.md
+++ /dev/null
@@ -1,53 +0,0 @@
-## Using TAESD to faster decoding
-
-You can use TAESD to accelerate the decoding of latent images by following these steps:
-
-- Download the model [weights](https://huggingface.co/madebyollin/taesd/blob/main/diffusion_pytorch_model.safetensors).
-
-Or curl
-
-```bash
-curl -L -O https://huggingface.co/madebyollin/taesd/resolve/main/diffusion_pytorch_model.safetensors
-```
-
-- Specify the model path using the `--taesd PATH` parameter. example:
-
-```bash
-sd-cli -m ../models/v1-5-pruned-emaonly.safetensors -p "a lovely cat" --taesd ../models/diffusion_pytorch_model.safetensors
-```
-
-### Qwen-Image and wan (TAEHV)
-
-sd.cpp also supports [TAEHV](https://github.com/madebyollin/taehv) (#937), which can be used for Qwen-Image and wan.
-
-- 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
- ```
-
-- 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
- ```
-
-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.
-
-### Qwen Image 2.1 (TAEQI2.1)
-
-For Qwen Image 2.1, use [taeqi2_1](https://github.com/madebyollin/taesd), which supports 64-channel latents, 16x spatial scaling, and RGBA images.
-
-Download the official [safetensors weights](https://huggingface.co/madebyollin/taeqi2_1/blob/main/taeqi2_1.safetensors) directly; no conversion is needed:
-
-```bash
-curl -L -o taeqi2_1.safetensors https://huggingface.co/madebyollin/taeqi2_1/resolve/main/taeqi2_1.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`.
-
-`sd-server` accepts the same `--taesd` and `--taesd-preview-only` options; the preview method is selected per request instead of via `--preview`.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 27731e1cce..c667cd4b89 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -45,7 +45,7 @@ the intended output scale:
The two values can be set independently and apply across model components. The
default `0` preserves each model's built-in settings; `1` explicitly disables the
corresponding scaling. Overrides must be finite positive values. C API users can
-set `linear_scale` and `attn_scale` in `sd_ctx_params_t`.
+set the `linear_scale` and `attn_scale` context-option keys with `sd_opt_set_float()`.
If the problem persists after trying the relevant steps above,
[submit a bug report](https://github.com/leejet/stable-diffusion.cpp/issues/new?template=bug_report.yml).
diff --git a/docs/wan.md b/docs/wan.md
deleted file mode 100644
index 2031de7df0..0000000000
--- a/docs/wan.md
+++ /dev/null
@@ -1,285 +0,0 @@
-# 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()`.
-
-## 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
-```
-
-
-
-### Wan2.1 T2V 14B
-
-```
-.\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
-```
-
-
-
-
-
-### Wan2.1 I2V 14B
-
-```
-.\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
-```
-
-
-
-### Wan2.2 T2V A14B
-
-```
-.\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
-```
-
-
-
-### Wan2.2 I2V A14B
-
-```
-.\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
-```
-
-
-
-### 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.
-
-```
-.\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
-```
-
-Notes:
-
-- Recommended settings: `--sampling-method euler --steps 20 --cfg-scale 6.0`.
- `dpm++2m` produces heavy artifacts on S2V. 4 steps with the lightning LoRA
- (below) is the fast option.
-- Resolutions: width and height must be multiples of 16; the examples use
- multiples of 64. 832x480 is a fast starting point; generation cost scales
- with pixel area.
-- `--audio` accepts a WAV file; it is downmixed to mono and resampled to 16 kHz
- internally. Audio longer than the video is truncated, video longer than the
- audio is padded with silence. Pick `--video-frames` to match the audio:
- roughly `audio_seconds * 16` frames, capped at one chunk (77-81 frames,
- ~5 s at the model's 16 fps). 33, 77 and 81 map to clean latent frame counts.
-- S2V always uses 16 fps. Other requested frame rates are automatically
- changed to 16 with a warning, including the CLI and server video output.
- `generate_video()` returns the actual frame rate through `fps_out`; C API
- callers should use that value when encoding the output video.
-- One generation covers the first S2V chunk window (`--video-frames` frames).
- Long-video chunked extend mode is not implemented yet.
-- Speed: the lightx2v lightning LoRA works with S2V at 4 steps and
- `--cfg-scale 1.0`. Use the **low_noise** variant;
- the high_noise variant produces artifacts on S2V:
-
- ```
- --lora-model-dir ..\models\loras
- -p "...
-
-### Wan2.2 T2V 14B with Lora
-
-```
-.\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
-
-### Z-Image-Base
-
-```
-.\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
-```
-
-
-
-## Comparison of Different Quantization Types
-
-| bf16 | q8_0 | q6_K | q5_0 | q4_K | q4_0 | q3_K | q2_K|
-|---|---|---|---|---|---|---|---|
-|
|
|
|
|
|
|
|
|
\ No newline at end of file
diff --git a/docs/z_image_l2p.md b/docs/z_image_l2p.md
deleted file mode 100644
index a7836f54df..0000000000
--- a/docs/z_image_l2p.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# 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.
-
-## Download weights
-
-- 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
-
-## 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
-```
diff --git a/examples/cli/CMakeLists.txt b/examples/cli/CMakeLists.txt
index 90164cfc02..36b9243e35 100644
--- a/examples/cli/CMakeLists.txt
+++ b/examples/cli/CMakeLists.txt
@@ -14,7 +14,6 @@ if(APPLE)
endif()
target_include_directories(${TARGET} PRIVATE
"${CMAKE_CURRENT_SOURCE_DIR}/.."
- "${PROJECT_SOURCE_DIR}/src"
)
install(TARGETS ${TARGET} RUNTIME)
target_link_libraries(${TARGET} PRIVATE stable-diffusion zip ${CMAKE_THREAD_LIBS_INIT})
diff --git a/examples/cli/README.md b/examples/cli/README.md
index 5789455491..0316f7bd02 100644
--- a/examples/cli/README.md
+++ b/examples/cli/README.md
@@ -1,18 +1,36 @@
# 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
```
+See [sampling methods and schedulers](../../docs/guides/sampling.md) for supported
+names, defaults, and custom sigma schedules.
+
+Omitted inference options use the [library defaults](../../docs/guides/c_api.md#keys).
+In particular, an omitted seed requests a random seed; use `--seed 42` for a
+repeatable run. Video generation defaults to 6 requested frames before model
+alignment. SLG layers remain unset unless `--skip-layers` is supplied, and the
+conditioning cache uses the library default. Zero and false are explicit inputs;
+invalid values are reported rather than treated as omitted.
+
Logging defaults to `info`. Use `--log-level