mlx-gen 0.18.12

Generative image and video model runtimes for MLX.

MLX-Gen

MLX-Gen is a local image and video generation runtime for Apple Silicon and MLX. It exposes mlxgen for text-to-image, image-to-image, text-to-video, image-to-video, model download, model preparation, quantized local folders, and application progress callbacks. It also includes the dedicated mflux-upscale-seedvr2 command for SeedVR2 image super-resolution.

[!IMPORTANT] MLX-Gen started as a fork of mflux. Most credit for the current codebase goes to Filip Strand and the original mflux contributors. This project keeps that attribution visible while publishing independently as mlx-gen and evolving the mlxgen command surface for current Apple Silicon workflows.

What It Does

MLX-Gen runs supported Hugging Face and prepared MLX-Gen model folders without starting network downloads during generation. You explicitly download or prepare models first, then generation is a cache-only operation suitable for desktop apps, workflow engines, and long-running local jobs.

The main capabilities are:

• text-to-image generation with Qwen Image, FLUX.2 Klein, Z-Image, ERNIE Image Turbo, Bonsai Image, FIBO, and related prepared folders;
• image-to-image modes, including latent img2img, instruction/reference edits, and multi-reference edits where the selected model supports them;
• Wan2.2 text-to-video and image-to-video, including TI2V-5B BF16/q8 packages plus A14B T2V/I2V prepared BF16 and mixed q8/BF16 packages; Wan I2V resolves output size from the source image aspect ratio so inputs are not stretched into a mismatched canvas;
• SeedVR2 image super-resolution through mflux-upscale-seedvr2, with shortest-edge target sizing or explicit scale factors such as 2x and 3x;
• explicit download and prepare workflows for reproducible local model folders;
• JSON model capability inspection before starting a heavy run;
• shared progress events for applications embedding MLX-Gen.

Use mlxgen capabilities --model ... before long image-edit runs. Capability output describes the available route; validation reports and contact sheets describe whether an exact source handle or prepared package passed a visual release gate. Release evidence should use true handles such as briaai/Fibo-Edit or AbstractFramework/flux.2-klein-9b-8bit, not short aliases.

Install

Install with uv:

uv tool install --upgrade mlx-gen

Or install into an environment:

python -m pip install -U mlx-gen

Check the command surface:

mlxgen --help

First Commands

Download model files explicitly:

mlxgen download --model AbstractFramework/flux.2-klein-9b-8bit

Generate an image:

mlxgen generate \
  --model AbstractFramework/flux.2-klein-9b-8bit \
  --prompt "A cinematic wide shot of a compact sci-fi spaceship resting in deep snow on a frozen alien planet" \
  --width 768 \
  --height 432 \
  --steps 24 \
  --guidance 1.0 \
  --seed 6107 \
  --output spaceship.png

Upscale an image with SeedVR2:

mflux-upscale-seedvr2 \
  --image-path input.png \
  --resolution 2x \
  --quantize 8 \
  --softness 0.25 \
  --metadata \
  --output input_2x.png

For SeedVR2, an integer --resolution is the target shorter edge while values such as 2x and 3x are scale factors. Both modes preserve the source aspect ratio. Use --softness 0.25 to 0.5 when the source has visible grain in smooth areas; keep the default no-tiling path for best quality, and add --vae-tiling only for very large memory-bound upscales. See docs/upscaling.md for a reproducible 5x SeedVR2 comparison.

Inspect model capabilities before a run:

mlxgen capabilities --model AbstractFramework/flux.2-klein-9b-8bit

Capabilities are route contracts: they show which tasks, I2I modes, image counts, and options the selected model can dispatch. For release QA evidence on exact packages, use:

mlxgen validation --model AbstractFramework/qwen-image-edit-2509-8bit

Create a reusable local prepared folder:

mlxgen prepare \
  --model Qwen/Qwen-Image \
  --path ./models/qwen-image-8bit \
  --quantize 8

mlxgen generate does not download missing files. If something is not cached, MLX-Gen raises a clear DownloadRequiredError with the command to run. A complete prepared folder at ./models/<repo-name> can also satisfy a matching Hugging Face handle such as AbstractFramework/qwen-image-edit-2511-8bit.

Reproducible Example

The docs include a complete model-backed spaceship workflow:

• T2I: generate a spaceship in the snow.
• I2I edit: turn it into a pencil sketch.
• I2I edit: crash the same spaceship in the snow.
• I2I multi-reference: combine the crash layout and pencil-sketch style.
• T2V A14B: generate a spaceship taking off from a snow planet.
• I2V A14B: animate the generated spaceship taking off from the source image.

See docs/examples/spaceship-snow.md for the exact commands and included assets.

For current image-edit validation evidence across Qwen Image Edit, Qwen EditPlus, FLUX.2 Klein, and latent I2I models, see docs/edit-capabilities.md.

Published Models

Prepared MLX-Gen model folders are published under the AbstractFramework organization on Hugging Face. Current published examples include:

• AbstractFramework/flux.2-klein-4b-4bit
• AbstractFramework/flux.2-klein-4b-8bit
• AbstractFramework/flux.2-klein-9b-4bit
• AbstractFramework/flux.2-klein-9b-8bit
• AbstractFramework/qwen-image-2512-4bit
• AbstractFramework/qwen-image-2512-8bit
• AbstractFramework/qwen-image-edit-2509-8bit
• AbstractFramework/qwen-image-edit-2511-4bit
• AbstractFramework/qwen-image-edit-2511-8bit
• AbstractFramework/z-image-turbo-4bit
• AbstractFramework/z-image-turbo-8bit
• AbstractFramework/ernie-image-turbo-4bit
• AbstractFramework/ernie-image-turbo-8bit
• AbstractFramework/wan2.2-ti2v-5b-diffusers-bf16
• AbstractFramework/wan2.2-ti2v-5b-diffusers-8bit
• AbstractFramework/wan2.2-t2v-a14b-diffusers-bf16
• AbstractFramework/wan2.2-t2v-a14b-diffusers-8bit
• AbstractFramework/wan2.2-i2v-a14b-diffusers-bf16
• AbstractFramework/wan2.2-i2v-a14b-diffusers-8bit

Use mlxgen download --model <repo-id> to cache a published model, or pass the repository id directly to mlxgen generate after it is cached. See docs/quantization.md for the complete current package matrix with source sizes, prepared package sizes, task coverage, and quantization notes.

For Wan2.2 TI2V-5B, the published BF16 prepared package is 21.2 GiB versus 31.9 GiB for the upstream source snapshot. It is mainly a smaller reusable source-equivalent package because MLX-Gen already loads Wan transformer/VAE weights at BF16 runtime precision. The published q8 package is 16.9 GiB. In the documented 1280x704 benchmark profile, q8 reduced logical model footprint and MLX allocator peak but did not reduce full-process physical peak memory. Wan TI2V-5B q4 or mixed q4/q8 is not published as a supported package. See the exact benchmark profile in docs/quantization.md.

Wan A14B Measurements

Wan A14B was measured on an Apple M5 Max with 128 GB unified memory. The published-card benchmark uses small, repeatable low-RAM runs and records full-process Darwin physical footprint, RSS, MLX allocator peak, and generation time. Use these values for the listed profiles; memory and runtime scale with resolution, frame count, step count, cache settings, and image-to-video conditioning.

Model	Package	Disk	Physical Peak	Max RSS	MLX Peak	Time	Profile
Wan2.2 T2V-A14B	BF16	64.1 GiB	33.0 GiB	31.8 GiB	27.7 GiB	152.7 s	384x224, 33 frames, 12 steps, 8 fps
Wan2.2 T2V-A14B	mixed q8/BF16	39.5 GiB	20.7 GiB	19.5 GiB	15.5 GiB	154.8 s	384x224, 33 frames, 12 steps, 8 fps
Wan2.2 I2V-A14B	BF16	64.1 GiB	33.7 GiB	31.8 GiB	28.2 GiB	228.2 s	384x384, 33 frames, 12 steps, 8 fps
Wan2.2 I2V-A14B	mixed q8/BF16	39.5 GiB	21.5 GiB	19.6 GiB	15.9 GiB	242.2 s	384x384, 33 frames, 12 steps, 8 fps

In these runs, mixed q8/BF16 reduces disk usage by about 38% versus prepared BF16 folders and reduces full-process physical peak memory by about 36-37%. It is not documented as a speed improvement. See docs/quantization.md for model-family quantization details and metrics JSON. The 0.18.11 release also validates the published A14B q8 T2V/I2V handles on a 41-frame, 15-step, 480x240-target profile with saved MP4/contact-sheet evidence in the quantization docs.

Ecosystem

MLX-Gen is used as the local Apple Silicon generation backend for:

• AbstractVision, the vision/generation layer of the AbstractFramework ecosystem;
• AbstractFramework, the broader framework for local agentic and generative workflows;
• AbstractFlow, a visual orchestration layer that can compose generative capabilities with persistent agentic tasks.

MLX-Gen remains useful as a standalone CLI package, but its cache-only runtime behavior, capability inspection, prepared model folders, and progress callbacks are designed so applications can embed it without surprise network transfers or ambiguous model routing.

Documentation

• Getting started: installation, first runs, SeedVR2 upscaling, and Wan video.
• API and CLI: command surface, router behavior, image-to-image modes, SeedVR2 sizing, Wan video sizes, capabilities, and Python entry points.
• Example workflow: reproducible image and video commands.
• Image upscaling: SeedVR2 sizing, quality controls, and a 5x source/output comparison.
• Image edit capabilities: visual edit-validation contact sheets, exact model/package status, and command logs.
• Model management: download, prepare, cache-only runtime policy.
• Quantization: q8/q4/BF16 policies and measurements.
• Python integration: embedding, progress callbacks, and AbstractVision notes.
• FAQ: recurring questions, image-to-image mode selection, SeedVR2 sizing, Qwen edit variants, negative prompts, outpaint/reframe status, Wan resolutions, and usage limits.
• Troubleshooting: common setup and runtime failures.
• Acknowledgements: upstream mflux and model-community credits.

License

MLX-Gen is MIT licensed. Model weights remain governed by their original licenses and access terms.