mfluxible

A minimal streaming HTTP API for image generation on Apple Silicon, built on mflux. Runs most of the image models mflux supports — fifteen checkpoints across Z-Image, FLUX.1, FLUX.2 Klein, Qwen-Image, Krea-2 and ERNIE-Image — one model per server process, configured at startup (see Models; Z-Image-Turbo is the default).

Rather than a full node-graph tool (ComfyUI) or a proprietary format (Draw Things), this exposes a small API in the same spirit as a chat-completions endpoint: each denoising step streams as a "thinking" event while generation happens, with optional in-progress preview images (Draw Things-style), followed by the final image.

Layout

mfluxible/          the model + HTTP API (FastAPI), and the detection sidecar
clients/            everything that talks to it: terminal scripts, a browser harness, an MCP tool
Caddyfile.example   optional: a reverse proxy that puts a bearer token in front of the API

Two packages are published from here, and they stay separate so that neither install drags in the other's dependencies:

Quickstart

Requires Python 3.11+ on Apple Silicon.

pip install mfluxible
mfluxible-server

That listens on 127.0.0.1:8420; --host, --port and --config are the flags, and mfluxible-server --help lists them. Everything else is configured with environment variables or a config file.

uv venv --python 3.11
uv pip install -e .

uv run mfluxible-server --host 127.0.0.1 --port 8420

The model loads on startup, before the server accepts any requests. On first run this downloads its weights from Hugging Face — expect a sizable one-time download — then quantizes them and caches the quantized copy (see Model cache); both only happen once.

The default model is Z-Image-Turbo (Tongyi-MAI/Z-Image-Turbo). To run something else, set MFLUXIBLE_MODEL (or model in a config file) before starting the server — fifteen checkpoints across Z-Image, FLUX.1, FLUX.2 Klein, Qwen-Image, Krea-2 and ERNIE-Image are supported; only the model you select is ever downloaded. See Models for the full table, what differs between them, and roughly how much memory each needs — 8.6 GB to 31 GB of weights at the default quantization, about half that at MFLUXIBLE_QUANTIZE=4.

Once it's running:

curl -N -X POST http://127.0.0.1:8420/mfluxible/v1/images/generations \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "a puffin on a cliff at sunset", "preview_every": 2}'

or use one of the clients for something more visual.

Documentation

• Clients — the bundled terminal scripts, the browser harness, and pointing a third-party frontend (OpenAI-compatible, or SillyTavern) at the server.
• MCP tool — generating images from an MCP client: what the tool does, how to register it with each tested client, and its own environment variables.
• API — every endpoint: the native streaming endpoint and its SSE event schema, image-to-image and fractional start, the OpenAI-compatible /v1 endpoints, and the AUTOMATIC1111-shaped txt2img shim SillyTavern needs.
• Server — running it: how a synchronous mflux call is streamed out of an async server, environment variables (memory, model cache, LoRAs, CORS), the models it can run, binding to the network, authentication, and troubleshooting.
• Contributing — for developers: the weight-free test suite and CI, what it takes to add another mflux model, and how a release is cut.
• Changelog — what changed in each version.

License

Apache 2.0.