VisualInference/FLUX-3-Image-Klein-MLX-8bit

FLUX 3 Image Klein, MLX 8bit

FLUX 3 Image Klein for Apple Silicon: text-to-image, editing with up to 10 reference images, and bounding-box layout, running natively in MLX with the flux3-mlx runner. The transformer is quantized to 8-bit; the output is validated against Black Forest Labs' reference implementation.

An independent community conversion, not affiliated with or endorsed by Black Forest Labs.

pip install "flux3-mlx[pup]"
flux3-mlx "a ceramicist's studio at golden hour, shelves of glazed bowls" --model 8bit --upsample --out studio.png

Gallery

Generated with this 8bit repo on an M4 Pro, 16 steps; prompts and seeds in gallery/*.json. Curated from a 27-prompt test set: edits, multi-reference and layout were consistently strong; some people shots were dropped for hand errors or smooth skin (see Limitations).

Edit: remove the car and its shadow	Three references -> one gallery wall
Edit: recolor the dress, keep the light	Bounding-box layout (boxes drawn on top)
Portra 400 portrait, overcast window light	Unretouched macro, Leica M6 on film
Vision3 250D road-movie still, 2.4:1	CineStill 800T, pushed, red halation
Upsampled from "night bus stop in the rain, CineStill 800T, one woman waiting under a red umbrella"	Two-color risograph poster: exact typography
1967 paperback cover, painted	Contact sheet with grease-pencil notes
4x5 still life, hard window light	Product macro: chrome and resin
Architectural interior, blue hour	65mm landscape, lone walker
Upsampled from 12 words: "a halved pomegranate on a plaster plinth, hard window light, Portra 400"

Which repo?

Repo	Transformer	Download	Peak memory, 1024²	Peak, --low-memory	For
MLX-8bit	8-bit, 6.15 GB	9.6 GB	14.3 GB	11.0 GB	Macs with 24 GB or more. Closest to BF16.
MLX-6bit	6-bit, 4.83 GB	8.4 GB	13.0 GB	9.6 GB	16 GB Macs (low-memory mode is on by default below 24 GB).

Prompt upsampler (recommended for short prompts): pup-MLX-4bit / pup-MLX-8bit.

There is no 4-bit repo on purpose: in our tests 4-bit added 5–23% high-frequency grain and changed design details (see Validation).

Usage

flux3-mlx "Full-color photograph, ..." --model 8bit --width 1216 --height 832 --seed 7   # long prompts as-is
flux3-mlx "a red bicycle in the rain" --model 8bit --upsample                            # short prompts: upsample
flux3-mlx "put a red bandana around the dog's neck" --model 8bit --image dog.png --upsample   # edit
flux3-mlx "the jacket from image 2 on the person in image 1" --model 8bit --image a.png --image b.png --upsample
flux3-mlx "balloons over a valley at sunrise" --model 8bit --boxes boxes.json --upsample        # layout

from flux3_mlx import Flux3Klein
pipe = Flux3Klein.from_pretrained("8bit", upsampler="4bit")
image, record = pipe("a ceramicist's studio at golden hour", seed=3)

Klein works best with fully described scenes: medium, framing, subjects with colors and materials, background, lighting. The upsampler writes such captions from short requests, edit instructions and box layouts. Seeds match the BFL reference: the same seed gives the same starting noise.

Performance (M4 Pro, 48 GB, 1024², 16 steps)

~115 s per image, 14.3 GB peak (11.0 GB with --low-memory). Every reference image adds its own tokens: measured on 8-bit, edits take ~200–270 s with one reference, ~290 s with two and ~540 s with three (each about 1 MP). The upsampler adds ~10–20 s. At 1 MP the model is compute-bound, so quantization saves memory rather than time. Keep the 16 steps: at 4 steps the output is visibly under-denoised and grainy, in BFL's own code too.

Validation

Compared with BFL's reference code (commit 45e57c9) and BFL's published example images:

Check	Result
Text encoder: tokens, template, hidden states (8 layers)	identical ids; mean cos ≥ 0.9999
VAE encode/decode	cos 1.000000
Transformer velocity, t2i and edit	cos 0.9999
BF16 port vs BFL's man_dog.png (B200), 1024², seed 7	35.9 dB, visually indistinguishable
This repo vs BFL's man_dog.png	34.2 dB
This repo texture vs BF16 (high-frequency energy, 1.00 = identical)	0.99

Quantization study across five cases (photo, typography, fashion, still life, edit):

Transformer	Texture vs BF16	Verdict
8-bit	0.99	shipped
6-bit	1.00	shipped
5-bit	0.95	blurs
4-bit (g32, g64, mixed 4/6, mixed 4/8)	1.05–1.18	grain, design changes

What is in this repo

Path	Content
transformer/	FLUX 3 Image Klein (distilled, flow map) DiT. Linear layers in the 43 transformer blocks are 8-bit (group size 64, affine). Modulation, time, input embeddings and final layer stay BF16.
text_encoder/	Text path of Qwen3-VL-4B-Instruct (byte-identical to BFL's bundled encoder), layers 0–31 only (Klein reads layers 4…32), 8-bit. Apache-2.0.
vae/ae.safetensors	The FLUX autoencoder, unchanged (fp32).
config.json	Repo manifest for the flux3-mlx runner (format version, components, sampler defaults)
LICENSE.md, NOTICE.md	FLUX Kommunity License and Attribution Notice
gallery/	Example images with their prompts, seeds and timings

Source: black-forest-labs/flux-3-image-klein model.safetensors (sha256 c3e9813c…, matching BFL's manifest).

Limitations

• Same as the original model (see BFL's card):
  • Text rendering can be inaccurate.
  • Edits can change content outside the requested region.
  • Prompt following depends on prompt style.
• What we saw in our own 27-prompt test (on the BF16 reference as much as here, so these are model traits, not conversion artifacts): occasional hand and finger errors, and smooth, slightly waxy skin or a familiar "Flux face" on some portraits. Detailed prompts (or --upsample) and a few seeds help; edits, multi-reference and layout were reliably strong.
• 16 steps at about 7 s/step on an M4 Pro. 4K output is supported by the code but impractically slow on current Macs.
• No safety classifier is bundled. Under the license, Qualifying Users who use outputs commercially must apply content filtering or review.

License

These weights are a Derivative of FLUX 3 Image Klein and are distributed under the FLUX Kommunity License. Any rights to use them are granted directly by Black Forest Labs Inc. under that License.

• Non-commercial use only. Qualifying Users (under US$5M gross annualized revenue) may use Outputs commercially, subject to the License.
• See BFL's licensing page for other commercial uses.
• The bundled text encoder is Apache-2.0 (text_encoder/LICENSE).

Attribution Notice: This FLUX Model is licensed by Black Forest Labs Inc. under the FLUX Kommunity License. Copyright Black Forest Labs Inc. IN NO EVENT SHALL BLACK FOREST LABS INC. BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH USE OF THIS MODEL.

Modification: this repository contains a modified version of FLUX 3 Image Klein. The weights were converted to the MLX format and the transformer was quantized to 8-bit; the text encoder was truncated to the layers the model reads and quantized to 8-bit.