---

name: generation description: "Run and troubleshoot sd-scripts image generation and minimal inference CLIs, including txt2img, img2img, inpainting, prompt files, SDXL conditioning, LoRA/network application, ControlNet/LLLite, and model-family inference scripts." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

sd-scripts Generation

Use this sub-skill when the user wants to generate images, validate prompt files, apply trained LoRA weights during inference, or diagnose generation failures. For LoRA training route to ../training; for model merging/conversion route to ../model-utilities; for dataset TOML route to ../data-preparation.

Choose the Entry Point

• Use gen_img.py for SD 1.x, SD 2.x, SDXL, txt2img, img2img, inpainting-by-mask, prompt files, highres fix, LoRA networks, ControlNet, and ControlNet-LLLite.
• Use sdxl_gen_img.py when you want the SDXL-focused script surface and the same prompt-file conventions.
• Use gen_img_diffusers.py when the model is a Diffusers pipeline/folder and the user wants Diffusers-style loading.
• Use inpainting_minimal_inference.py for a small inpainting script with --ckpt_path, --image, --mask, and --sdxl rather than the broader gen_img.py interface.
• Use family minimal inference scripts for newer architectures: sdxl_minimal_inference.py, sd3_minimal_inference.py, flux_minimal_inference.py, lumina_minimal_inference.py, hunyuan_image_minimal_inference.py, anima_minimal_inference.py, and anima_minimal_inference_control_net_lllite.py.

Fast Start Commands

Keep commands model-path agnostic and replace placeholders with the user’s files:

python gen_img.py --ckpt <model.ckpt-or-safetensors-or-diffusers-id> --outdir outputs \
  --fp16 --xformers --W 512 --H 768 --steps 30 --sampler k_euler_a \
  --prompt "masterpiece, detailed illustration --n low quality, blurry"

python gen_img.py --ckpt <model> --outdir outputs --bf16 --sdpa --no_preview \
  --from_file prompts.txt --images_per_prompt 4 --batch_size 2 --seed 1234

python gen_img.py --ckpt <sdxl-model> --sdxl --outdir outputs --bf16 --sdpa \
  --original_width 1024 --original_height 1024 --target_width 1024 --target_height 1024 \
  --prompt "cinematic studio portrait --n distorted face"

Before running a batch, validate prompt-file syntax without loading models:

python skills/sd-scripts/sub-skills/generation/scripts/validate_prompt_file.py prompts.txt --family gen-img

Required References

• references/commands.md: command templates for txt2img, img2img, inpainting, SDXL, LoRA, ControlNet, LLLite, and minimal inference scripts.
• references/prompt-formats.md: prompt-file syntax, negative prompts, prompt weights, dynamic prompts, per-line options, and model-family differences.
• references/troubleshooting.md: diagnosis for model-family flags, path errors, headless preview, precision artifacts, xformers/SDPA, OOM, LoRA count mismatch, ControlNet mismatches, and offline tokenizer cache.

Practical Workflow

1. Identify the model family first: SD1/SD2/SDXL uses gen_img.py; SD3/Flux/Lumina/Hunyuan/Anima use family minimal inference scripts.
2. Confirm required model components exist: checkpoint or DiT plus text encoders plus VAE/AE as required by the selected script.
3. Select precision and memory flags conservatively: start with --fp16 or --bf16, reduce --batch_size, reduce resolution, then add VAE slicing/offload flags if needed.
4. Validate prompt files with the bundled script; it catches malformed per-line options, missing values, invalid numeric fields, and likely LoRA multiplier count mistakes.
5. If applying LoRA at inference, match each --network_module with a --network_weights entry for gen_img.py, or use the family script’s --lora_weights/--lora_weight convention.
6. For ControlNet/LLLite, verify image, mask, and control dimensions and ensure ControlNet and LLLite are not mixed in one gen_img.py command.

Common Decisions

• Prefer --no_preview on servers, containers, CI, SSH sessions, and any headless environment.
• Prefer --sdpa on modern PyTorch when xformers is unavailable; use --xformers only when the package is installed and compatible.
• For SD2 v-parameterized checkpoints, include both --v2 and --v_parameterization; missing --v_parameterization can produce brown images.
• For black images or NaNs, retry with --bf16, --no_half_vae, lower resolution, or fp32 depending on hardware support.
• For prompt weighting, use WebUI-like (term:1.2), (term), and [term]; keep generation options separated with spaces, such as prompt text --n bad anatomy --w 768.