OpenClaw-mflux-Skill

description: Local image generation using Apple MLX via mflux — FLUX.2 Klein 4B (fast, Apache 2.0) and Z-Image Turbo (quality) models

SKILL.md — mflux

Name

mflux

Description

Generate images locally using Apple Silicon via the mflux MLX implementation. Supports FLUX.2-klein-4B (default, fastest 4-step generation, Apache 2.0 licensed) and Z-Image-Turbo (6B, highest quality). All processing is on-device — no cloud, no API keys, no data leaving your Mac.

Requirements

• Apple Silicon Mac (M1 or later)
• Python 3.10+
• macOS 13.5+
• Recommended: 16GB+ RAM (8GB works with quantization)

Installation

1. Install mflux (via uv - recommended)

uv tool install --upgrade mflux --prerelease=allow

With faster downloads (optional):

uv tool install --upgrade mflux --with hf_transfer --prerelease=allow

2. Alternative: Install via pip

pip install -U mflux

3. Verify installation

mflux-generate --help
mflux-generate-z-image-turbo --help
mflux-generate-flux2 --help

Python API Usage

Quick Start — FLUX.2 Klein 4B (Default, Fastest)

from mflux.models.flux2.variants import Flux2Klein
from mflux.models.common.config import ModelConfig

model = Flux2Klein(model_config=ModelConfig.flux2_klein_4b())
image = model.generate_image(
    prompt="A serene Japanese garden with cherry blossoms, golden afternoon light",
    num_inference_steps=4,  # Only 4 steps needed!
    width=1024,
    height=768,
    seed=42,
)
image.save("garden.png")

Z-Image Turbo (Highest Quality)

from mflux.models.z_image import ZImage
from mflux.models.common.config import ModelConfig

model = ZImage(
    model_config=ModelConfig.z_image_turbo(),
    model_path="filipstrand/Z-Image-Turbo-mflux-4bit",  # 4-bit quantized
)
image = model.generate_image(
    prompt="A majestic eagle soaring over snow-capped mountains at sunset",
    num_inference_steps=9,
    width=1280,
    height=720,
    seed=42,
)
image.save("eagle.png")

With Quantization (Lower RAM)

from mflux.models.flux2.variants import Flux2Klein
from mflux.models.common.config import ModelConfig

model = Flux2Klein(
    model_config=ModelConfig.flux2_klein_4b(),
    quantize=8,  # 8-bit quantization
)
# ... generate image

Image-to-Image

from PIL import Image
from mflux.models.flux2.variants import Flux2Klein

model = Flux2Klein(model_config=ModelConfig.flux2_klein_4b())
image = model.generate_image(
    prompt="Transform into a watercolor painting",
    num_inference_steps=4,
    init_image=Image.open("source.jpg"),
    init_image_strength=0.3,  # 0.0-1.0, higher = more change
)
image.save("watercolor.png")

FLUX.2 Image Editing

from mflux.models.flux2.variants import Flux2KleinEdit
from mflux.models.common.config import ModelConfig

model = Flux2KleinEdit(model_config=ModelConfig.flux2_klein_4b())
image = model.generate_image(
    prompt="Make the person wear sunglasses",
    image_paths=["person.jpg", "sunglasses.jpg"],
    num_inference_steps=4,
    seed=42,
)
image.save("edited.png")

LoRA Support

from mflux.models.flux2.variants import Flux2Klein
from mflux.models.common.config import ModelConfig

model = Flux2Klein(
    model_config=ModelConfig.flux2_klein_4b(),
    lora_paths=["path/to/lora.safetensors"],
    lora_scales=[0.8],
)
# ... generate image

Supported Models

| Model | CLI Command | Size | Steps | Speed | Quality | License | |-------|-------------|------|-------|-------|---------|---------| | FLUX.2-klein-4b (default) | mflux-generate-flux2 | 4B | 4 | ⚡ Fastest | ⭐⭐⭐⭐ | Apache 2.0 | | FLUX.2-klein-9b | mflux-generate-flux2 | 9B | 4 | ⚡ Fast | ⭐⭐⭐⭐⭐ | Apache 2.0 | | Z-Image-Turbo | mflux-generate-z-image-turbo | 6B | 9 | ⚡ Fast | ⭐⭐⭐⭐⭐ | Custom | | Z-Image (base) | mflux-generate-z-image | 6B | 50 | 🐢 Slow | ⭐⭐⭐⭐⭐ | Custom | | FLUX.2-klein-base-4b | mflux-generate-flux2 | 4B | 50 | 🐢 Slowest | ⭐⭐⭐⭐⭐ | Apache 2.0 | | Qwen-Image | mflux-generate-qwen | 20B | 20 | 🐢 Slow | ⭐⭐⭐⭐⭐⭐ | Custom |

CLI Reference

Generate with FLUX.2 Klein

# Default 4B model, 4 steps
mflux-generate-flux2 \
  --prompt "A photorealistic portrait of a wise old sailor" \
  --width 1024 \
  --height 768 \
  --steps 4 \
  --seed 42

# 9B model for higher quality
mflux-generate-flux2 \
  --model flux2-klein-9b \
  --prompt "A cyberpunk cityscape with neon lights" \
  --steps 4

# Base model (non-distilled, more steps)
mflux-generate-flux2 \
  --model flux2-klein-base-4b \
  --prompt "A detailed oil painting of a forest" \
  --steps 50 \
  --guidance 1.5

Generate with Z-Image Turbo

mflux-generate-z-image-turbo \
  --prompt "A minimalist logo design for a coffee shop" \
  --width 1280 \
  --height 720 \
  --steps 9 \
  --seed 42

# With LoRA
mflux-generate-z-image-turbo \
  --prompt "Art nouveau style portrait of a woman" \
  --steps 9 \
  --lora-paths "renderartist/Art-Nouveau-Style" \
  --lora-scales 0.7

With Quantization

mflux-generate-flux2 \
  --prompt "A serene landscape" \
  --quantize 8  # 8-bit quantization (reduces RAM)

# Or 4-bit for lowest RAM
mflux-generate-flux2 \
  --prompt "A serene landscape" \
  --quantize 4

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | prompt | str | required | Text description of image | | width | int | 1024 | Image width in pixels | | height | int | 768 | Image height in pixels | | num_inference_steps | int | 4 (Klein), 9 (Z-Image) | Number of denoising steps | | seed | int | random | Random seed for reproducibility | | quantize | int | None | Quantization level (4, 8) | | guidance | float | 1.0 (Klein) / 4.0 (Z-Image) | Guidance scale (base models only) | | lora_paths | list | None | List of LoRA file paths | | lora_scales | list | None | LoRA blending scales | | init_image | PIL.Image | None | Source image for img2img | | init_image_strength | float | 0.3 | Strength of transformation |

Aspect Ratios (Recommended Sizes)

| Aspect Ratio | Dimensions | Use Case | |--------------|------------|----------| | 1:1 | 1024×1024 | Profile photos, icons | | 4:3 | 1024×768 | Photo standard | | 16:9 | 1024×576 or 1280×720 | Landscape, videos | | 3:4 | 768×1024 | Portrait orientation | | 9:16 | 720×1280 | Mobile vertical | | 21:9 | 1280×550 | Cinematic widescreen |

Performance & RAM Guide

| Configuration | RAM | Speed | Best For | |-------------|-----|-------|----------| | FLUX.2-klein-4b, q=8 | ~5 GB | ~8 sec | 8GB Macs | | FLUX.2-klein-4b, q=4 | ~4 GB | ~5 sec | Low RAM | | FLUX.2-klein-4b, q=None | ~8 GB | ~15 sec | Quality on 16GB | | FLUX.2-klein-9b, q=8 | ~12 GB | ~20 sec | Best quality 16GB | | Z-Image-Turbo, q=4 | ~5 GB | ~12 sec | All-around 8GB |

Model Weights

Models are downloaded automatically on first use:

• FLUX.2-klein-4b: ~15GB
• FLUX.2-klein-9b: ~32GB
• Z-Image-Turbo quantized: ~8GB

Cache location: ~/.cache/huggingface/

Comparison: When to Use Which

Choose FLUX.2-klein-4b when:

• Speed is priority (4 steps, ~5-8 sec)
• Apache 2.0 license needed (commercial use)
• Generating many images fast
• 8GB+ RAM available

Choose Z-Image-Turbo when:

• Quality is priority
• Realism matters most
• You have 16GB+ RAM
• Time per image acceptable

Choose FLUX.2-klein-9b when:

• Best quality from Apache-licensed model
• 16GB+ RAM available
• Commercial use required

Error Handling

| Error | Cause | Fix | |-------|-------|-----| | OutOfMemoryError | Not enough RAM | Use quantization (q=8, q=4) | | ValueError: Model not found | First run / cache issue