Image Generation¶

mlxcel generates and edits images with diffusion checkpoints through the mlxcel generate-image subcommand and the OpenAI-compatible POST /v1/images/generations and POST /v1/images/edits server routes. Diffusion models produce pixels rather than tokens, so image generation is a separate surface from generate and serve -m, the same way detect is separate for boxes.

A checkpoint the loader recognizes as an image model is refused by mlxcel generate and mlxcel serve -m with a message naming generate-image, and a checkpoint the probe recognizes but this build does not implement fails with image generation family <family> is not supported by this build.

Supported Families¶

The family is detected from the checkpoint directory's manifest.json, model_index.json, component configs, and transformer weight map. Detection reads JSON only and never loads weights, so a wrong directory or an unported family fails before any memory is spent.

CLI¶

mlxcel generate-image -m models/flux2-klein -p "a watercolor fox"
mlxcel generate-image -m models/flux2-klein -p "a fox" --size 768x512 --seed 7 -n 2 -o fox.png
mlxcel generate-image -m models/flux2-klein --task edit --image fox.png -p "make it night"

The command validates the model directory, the arguments, the reference images, and the output directory before it classifies the family or loads any weight. When a model rewrites the prompt (ERNIE-Image's prompt enhancer), the CLI prints revised prompt: <text> after the line naming each saved image.

FLUX.2 generation follows upstream mlx-vlm: the n images share one noise tensor drawn from seed and come from one prompt encode, so every image reports the same seed and image i is not the image seed + i gives on its own. Edits and the other families run once per image with seed seed + i.

--gen-kwargs carries model-specific knobs. FLUX.2 and Bonsai accept max_sequence_length and tiled_vae; Z-Image, ERNIE-Image, and the other families document their own options in docs/image-generation.md.

Server¶

mlxcel-server -m <chat model> --image-model <image checkpoint>

--image-model (also MLXCEL_IMAGE_MODEL, on both mlxcel-server and mlxcel serve) loads a side worker the way --embedding-model does: a dedicated thread owns the model, a bounded queue admits requests, and a per-request timeout frees the caller. A load failure is fatal at startup, so a command line that asked for image routes never answers 501 for them. Requests run one at a time, because a diffusion run holds the GPU for seconds; a full queue answers 503 and a timeout answers 504.

Image-only mode¶

Without -m, the image checkpoint is the served model rather than a side model:

mlxcel-server --image-model <image checkpoint> --port 8080
mlxcel serve --image-model <image checkpoint>

The served id is the first --alias entry when given, otherwise the checkpoint directory name, and /v1/models reports it with the image capability and no completion. /health follows the image worker. Chat and tokenizer routes, including /tokenize, /detokenize and /apply-template, answer the structured 501 that names --image-model and no -m. Image-only mode cannot be combined with --models-dir, --models-preset, --webui, --embedding-model, --reranker-model, --embeddings or --reranking; startup fails naming both flags. Passing -m as well keeps the two-model behavior above.

Without --image-model both routes answer 501 naming the flag. A request the family rejects before running is 400, and so is an InvalidImageRequest a model raises while running. Every other failure during generation is 500.

Request¶

generations accepts prompt, model, n (1 to 10), size (WxH) or width plus height, steps, seed, guidance, negative_prompt, response_format, and output_format. edits adds image, either one string or a list. Any other field is passed to the model as extra.

• width and height come together or not at all, and override size.
• size defaults to 512x512 for generation, and for editing to the first reference image's size or what the family derives from it.
• Width and height must be multiples of the family's grid, and the error names the multiple.
• response_format accepts only b64_json; url and path are 400. output_format accepts only png. output_path and output_dir are 400, because the server never writes files on behalf of a client.
• model, when non-empty, must equal the served model id.
• Each image is a data URL or a URL, read through the same limits as chat images; file:// URLs stay inside --media-path. A raw filesystem path is 400. Multipart upload is not served.

Response¶

{
  "created": 1790000000,
  "data": [
    {"b64_json": "iVBORw0KGgo...", "mime_type": "image/png",
     "width": 512, "height": 512, "seed": 7, "revised_prompt": null}
  ],
  "output_format": "png",
  "size": "512x512"
}

RGB and RGBA images are both encoded as they are, so an RGBA result keeps its alpha channel. revised_prompt is always present and is null unless the model rewrote the prompt.