mflux Image Generation Router#

You're helping someone generate images using mflux — an MLX-native image generation framework built for Apple Silicon. Instead of calling mflux as a subprocess on one machine, this routes mflux image generation requests across the fleet. The router picks the device with the mflux model loaded, the most free memory, and the lowest CPU load.

Why route mflux image generation#

One machine running mflux image generation blocks other workloads. An mflux 1024x1024 image takes ~18 seconds on an M3 Ultra. If an agent needs another mflux image during that time, it waits. With fleet routing, the second mflux request goes to a different device.

mflux image generation also competes with LLM inference for GPU memory. The router knows which nodes are busy with LLM requests and routes mflux image generation to the least-loaded device.

Zero cloud costs. A Mac Mini M4 running mflux generates images at $0/request after the hardware investment. DALL-E charges $0.04/image. At 80 mflux images per day, that's $96/month saved.

Get started with mflux#

bash

pip install ollama-herd
herd                        # start the mflux image generation router (port 11435)
herd-node                   # start on each device running mflux
uv tool install mflux       # install mflux on devices for image generation

Enable mflux image generation:

bash

curl -X POST http://localhost:11435/dashboard/api/settings \
  -H "Content-Type: application/json" \
  -d '{"image_generation": true}'

Package: ollama-herd | Repo: github.com/geeks-accelerator/ollama-herd

Generate an image with mflux#

curl — mflux image generation#

bash

# mflux image generation via fleet router
curl -o mflux_output.png http://localhost:11435/api/generate-image \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "a neon-lit Tokyo alley at midnight, cyberpunk aesthetic",
    "width": 1024,
    "height": 1024,
    "steps": 4,
    "quantize": 8
  }'

Python — mflux image generation#

python

import httpx

def mflux_generate_image(prompt, mflux_output_path="mflux_output.png", width=1024, height=1024):
    """Generate an image using mflux image generation via the fleet router."""
    mflux_resp = httpx.post(
        "http://localhost:11435/api/generate-image",
        json={
            "model": "z-image-turbo",
            "prompt": prompt,
            "width": width,
            "height": height,
            "steps": 4,
            "quantize": 8,
        },
        timeout=120.0,
    )
    mflux_resp.raise_for_status()
    with open(mflux_output_path, "wb") as f:
        f.write(mflux_resp.content)

    mflux_node = mflux_resp.headers.get("X-Fleet-Node", "unknown")
    mflux_time_ms = mflux_resp.headers.get("X-Generation-Time", "?")
    print(f"mflux image generation completed on {mflux_node} in {mflux_time_ms}ms")
    return mflux_output_path

JavaScript — mflux image generation#

javascript

async function mfluxGenerateImage(prompt, width = 1024, height = 1024) {
  // mflux image generation via fleet router
  const mflux_resp = await fetch("http://localhost:11435/api/generate-image", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "z-image-turbo", prompt, width, height, steps: 4, quantize: 8,
    }),
  });
  if (!mflux_resp.ok) throw new Error((await mflux_resp.json()).error);
  return Buffer.from(await mflux_resp.arrayBuffer());
}

mflux image generation parameters#

ParameterDefaultDescriptionmodel(required)z-image-turbo, flux-dev, or flux-schnell — mflux modelsprompt(required)Text description for mflux image generationwidth``1024mflux image width in pixelsheight``1024mflux image height in pixelssteps``4mflux inference steps (4 is optimal for z-image-turbo)quantize``8mflux quantization level (3-8 bit). 8 is the sweet spotseedrandomInteger seed for reproducible mflux outputnegative_prompt``""What to avoid in the mflux image

mflux image generation response#

• 200 OK: Raw PNG bytes from mflux. Content-Type: image/png
• X-Fleet-Node: Which device ran mflux image generation
• X-Fleet-Model: mflux model used
• X-Generation-Time: mflux generation time in milliseconds

Available mflux models#

mflux ModelSpeed (M3 Ultra)QualityUse casez-image-turbo~7s (512px), ~18s (1024px)GoodFast mflux iterationflux-dev~30s (1024px)HighestDetailed mflux photorealisticflux-schnell~10s (1024px)MediumFastest mflux variant

mflux image generation with request tags#

Track per-project mflux image generation in the dashboard:

bash

curl -o mflux_output.png http://localhost:11435/api/generate-image \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "your prompt for mflux image generation",
    "metadata": {"tags": ["mflux-project", "mflux-content-gen"]}
  }'

Also available on this fleet#

LLM inference#

bash

curl http://localhost:11435/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-oss:120b","messages":[{"role":"user","content":"Hello"}]}'

Speech-to-text#

bash

curl -s http://localhost:11435/api/transcribe \
  -F "audio=@recording.wav" | python3 -m json.tool

Embeddings#

bash

curl http://localhost:11435/api/embeddings \
  -d '{"model":"nomic-embed-text","prompt":"search query"}'

Monitoring mflux image generation#

bash

# mflux image generation stats (last 24h)
curl -s http://localhost:11435/dashboard/api/image-stats | python3 -m json.tool

# Fleet health (includes mflux image generation activity)
curl -s http://localhost:11435/dashboard/api/health | python3 -m json.tool

Dashboard at http://localhost:11435/dashboard — mflux image generation queues show with [IMAGE] badge.

Full documentation#

Agent Setup Guide — complete reference for all 4 model types including mflux.

Image Generation Guide — detailed mflux image generation API reference.

Guardrails#

• Never delete or modify mflux-generated images without explicit user confirmation.
• Never pull or delete mflux models without user confirmation — downloads can be 3+ GB.
• Never delete or modify files in ~/.fleet-manager/.
• If no mflux image generation models available, suggest installing: uv tool install mflux.