### Start Mflux Training

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/common/README.md

Use this command to start a new training run with a specified configuration file.

```sh
uv run mflux-train --config src/mflux/models/common/training/_example/train.json
```

--------------------------------

### Install mflux Shell Completions

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/cli/completions/README.md

Run this command to automatically install the mflux ZSH shell completions.

```bash
mflux-completions
```

--------------------------------

### Install MFLUX CLI

Source: https://github.com/filipstrand/mflux/blob/main/README.md

Installs or upgrades the MFLUX command-line interface using uv. Ensure uv is installed first.

```sh
uv tool install --upgrade mflux
```

--------------------------------

### Example JSON Prompt Structure

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/fibo/README.md

This is an example of a structured JSON prompt file used for image generation. It includes a short description and detailed object descriptions with their attributes.

```json
{
  "short_description": "Three cartoon animal chefs are in a bakery kitchen, each holding a culinary creation. A bunny chef on the left presents a chocolate cake, a raccoon chef in the center is frosting cupcakes, and a penguin chef on the right carries a tray of croissants. The kitchen is brightly lit with warm tones, and flour dusts the air, creating a lively and cheerful baking atmosphere.",
  "objects": [
    {
      "description": "A cartoon bunny wearing a white chef's hat and a pink apron, holding a chocolate cake with white frosting and cherries.",
      "location": "left foreground",
      "relationship": "The bunny chef is presenting the chocolate cake.",
      "relative_size": "medium",
      "shape_and_color": "Rounded bunny shape, white hat, pink apron, brown cake, white frosting, red cherries.",
      "texture": "smooth",
      "appearance_details": "Floppy ears, rosy cheeks, smiling expression.",
      "pose": "Standing upright, holding the cake with both hands.",
      "expression": "Joyful and proud.",
      "clothing": "White chef's hat, pink apron.",
      "action": "Holding and presenting a cake.",
      "gender": "female",
      "skin_tone_and_texture": "White fur, smooth texture.",
      "orientation": "Upright, facing forward."
    },
    {

```

--------------------------------

### Run FLUX.2 Training

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/flux2/README.md

Execute the mflux-train command with a specified configuration file to start the training process.

```sh
mflux-train --config /path/to/train.json
```

--------------------------------

### Generate Image with ERNIE-Image (CLI)

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/ernie_image/README.md

This command-line example demonstrates generating images with the base ERNIE-Image model, which typically requires more steps and supports classifier-free guidance. Use ERNIE-Image-Turbo for most tasks due to its speed.

```shell
mflux-generate-ernie-image \
  --prompt "Close-up portrait of a barn owl perched on a mossy branch, heart-shaped face, detailed feathers, soft forest bokeh, natural wildlife photography." \
  --width 1024 \
  --height 576 \
  --seed 404 \
  --steps 50 \
  --guidance 4.0 \
  -q 8
```

--------------------------------

### List MFLUX CLI Commands

Source: https://github.com/filipstrand/mflux/blob/main/README.md

Displays all available commands provided by the installed MFLUX CLI.

```sh
uv tool list 
```

--------------------------------

### Ideogram 4.0 Teapot Prompt Example

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/ideogram4/README.md

A sample prompt file for generating an image of a white ceramic teapot, focusing on a clean, minimal photographic style.

```json
{
  "high_level_description": "A white ceramic teapot on a simple studio table.",
  "style_description": {
    "aesthetics": "clean, calm, minimal",
    "lighting": "soft diffuse studio lighting",
    "photo": "eye-level, 50mm lens, shallow depth of field",
    "medium": "photograph",
    "color_palette": ["#FFFFFF", "#E5E0D8", "#2E2E2E"]
  },
  "compositional_deconstruction": {
    "background": "A neutral studio tabletop with a pale wall behind it.",
    "elements": [
      {
        "type": "obj",
        "bbox": [250, 320, 780, 690],
        "desc": "A glossy white ceramic teapot with a curved handle and short spout."
      }
    ]
  }
}
```

--------------------------------

### Install mflux Completions to Custom Directory

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/cli/completions/README.md

Use this command to install mflux shell completions to a specific directory, useful for custom ZSH configurations.

```bash
mflux-completions --dir ~/.config/zsh/completions
```

--------------------------------

### Install MFLUX with hf_transfer Support

Source: https://github.com/filipstrand/mflux/blob/main/README.md

Installs or upgrades MFLUX, including the 'hf_transfer' package for faster model downloads from Hugging Face. Use this if you encounter 'hf_transfer' related ValueErrors.

```sh
uv tool install --upgrade mflux --with hf_transfer
```

--------------------------------

### Generate Food Photography with mflux CLI

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/qwen/README.md

Generate a professional food photography image using the mflux CLI. This example focuses on gourmet Chinese cuisine.

```sh
mflux-generate-qwen \
  --prompt "Professional food photography, gourmet Chinese cuisine, steamed dumplings, colorful vegetables, traditional table setting, restaurant lighting, shallow depth of field, photorealistic, high detail, magazine quality" \
```

--------------------------------

### Check mflux Completion Installation

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/cli/completions/README.md

Verify that mflux shell completions are correctly installed and configured in your ZSH environment.

```bash
mflux-completions --check
```

--------------------------------

### Sequential Image Editing with Kontext

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/flux/README.md

Perform sequential edits on an image using mflux-generate-kontext. This example adds atmospheric mist to mountains, preserving other image elements. Requires specifying image path, prompt, steps, seed, guidance, and dimensions.

```bash
mflux-generate-kontext \
  --image-path "house_without_background_objects.png" \
  --prompt "Make the mountains in the background be covered in white mist so that they are barely visible. Preserve the original camera angle, house placement etc" \
  --steps 20 \
  --seed 9375333 \
  --guidance 2.5 \
  --width 912 \
  --height 1360 \
  -q 8
```

--------------------------------

### Generate Ideogram 4.0 Image with Custom Seed and Preset

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/ideogram4/README.md

Command-line example for generating an image using a prompt file, specifying dimensions, seed, and generation preset.

```bash
mflux-generate-ideogram4 \
  --prompt-file teapot-caption.json \
  --width 1024 \
  --height 1024 \
  --seed 42 \
  --preset V4_DEFAULT_20
```

--------------------------------

### Generate Chinese Calligraphy with mflux CLI

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/qwen/README.md

Generate an image of a Chinese calligraphy studio using the mflux CLI. This example focuses on cultural and artistic themes.

```sh
mflux-generate-qwen \
  --prompt "Traditional Chinese calligraphy studio, ancient scrolls with beautiful Chinese characters, ink brushes, inkstone, traditional paper, warm natural lighting, peaceful atmosphere, photorealistic, high detail, cultural heritage" \
  --negative-prompt "blurry, low quality, distorted, deformed, ugly, bad anatomy, bad proportions, extra limbs, duplicate, watermark, signature, text, letters, cartoon, anime, painting, drawing, illustration, 3d render, cgi, modern" \
  --width 1920 \
  --height 816 \
  --steps 30 \
  --seed 42 \
  -q 8
```

--------------------------------

### Create Outpainting Canvas and Mask (Padding Example)

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/flux/README.md

Expand the canvas of an image for outpainting. This command adds 25% padding to the left and right sides of the image, creating a new canvas and mask for further editing.

```bash
python tools/create_outpaint_image_canvas_and_mask.py \
  room.png \
  --image-outpaint-padding "0,25%,0,25%"
```

--------------------------------

### Update Existing mflux Completion Installation

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/cli/completions/README.md

Run this command to update an existing mflux completion file, ensuring you have the latest completions after an mflux upgrade.

```bash
mflux-completions --update
```

--------------------------------

### ControlNet Image Generation

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/flux/README.md

Utilize ControlNet for precise image generation by providing a prompt, model, and a reference image path. Adjust ControlNet strength for desired influence. This example also applies a LoRA adapter.

```bash
mflux-generate-controlnet \
  --prompt "A comic strip with a joker in a purple suit" \
  --model dev \
  --steps 20 \
  --seed 1727047657 \
  --height 1066 \
  --width 692 \
  -q 8 \
  --lora-paths "Dark Comic - s0_8 g4.safetensors" \
  --controlnet-image-path "reference.png" \
  --controlnet-strength 0.5 \
  --controlnet-save-canny
```

--------------------------------

### Example Full Edit JSON Prompt

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/fibo/README.md

This JSON structure defines a detailed prompt for FIBO-Edit, including descriptions of objects, background, lighting, and aesthetic preferences. Use this for advanced editing control.

```json
{
  "short_description": "A close-up shot of a Black man's hand making a fistbump gesture towards the camera. He is wearing a plain white t-shirt. The background is a softly blurred indoor setting with a window and curtains.",
  "objects": [
    {
      "description": "A Black man's hand, with visible knuckles and skin texture, making a fistbump gesture.",
      "location": "center foreground",
      "relationship": "The hand is the primary subject, making contact with the camera.",
      "relative_size": "large within frame",
      "shape_and_color": "Human hand shape, dark brown skin tone.",
      "texture": "Smooth skin with visible knuckles.",
      "appearance_details": "Fingers are curled into a fist, thumb is extended.",
      "orientation": "facing forward, fist extended towards the viewer"
    },
    {
      "description": "A Black man's torso and lower face, partially visible, wearing a white t-shirt.",
      "location": "center midground",
      "relationship": "The man is the owner of the hand, providing context for the gesture.",
      "relative_size": "medium",
      "shape_and_color": "Human torso and face shape, dark brown skin tone, white shirt.",
      "texture": "Smooth skin, soft fabric of the t-shirt.",
      "appearance_details": "He has a short beard and mustache. His expression is serious and direct.",
      "pose": "Upper body visible, arm extended forward for a fistbump.",
      "expression": "serious, direct gaze",
      "clothing": "plain white crew-neck t-shirt",
      "action": "fistbumping the camera",
      "gender": "male",
      "skin_tone_and_texture": "dark brown, smooth skin",
      "orientation": "upright, facing forward"
    }
  ],
  "background_setting": "A softly blurred indoor setting, featuring a light gray wall on the left, a window with natural light streaming through on the right, and sheer white curtains partially drawn.",
  "lighting": {
    "conditions": "bright indoor lighting, natural light from a window",
    "direction": "side-lit from right",
    "shadows": "soft shadows are cast on the left side of the hand and face, indicating light from the right window."
  },
  "aesthetics": {
    "composition": "centered, portrait composition with the hand as the focal point",
    "color_scheme": "neutral tones with a pop of white from the shirt and natural light.",
    "mood_atmosphere": "direct, engaging, slightly serious.",
    "photographic_characteristics": {
      "depth_of_field": "shallow",
      "focus": "sharp focus on the hand and face, with a blurred background",
      "camera_angle": "eye-level",
      "lens_focal_length": "standard lens (e.g., 35mm-50mm)"
    },
    "style_medium": "photograph",
    "artistic_style": "realistic, naturalistic",
    "preference_score": "very high",
    "aesthetic_score": "very high"
  }
}
```

--------------------------------

### Generate Image with Image-Guided Concept Analysis

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/flux/README.md

This command uses a reference image to guide concept attention analysis. It analyzes how a concept appears in the reference image and applies similar attention patterns to generate a new image.

```bash
mflux-concept-from-image \
  --model schnell \
  --input-image-path "puffin.png" \
  --prompt "Two puffins are perched on a grassy, flower-covered cliffside, with one appearing to call out while the other looks on silently against a blurred ocean backdrop" \
  --concept "bird" \
  --steps 4 \
  --height 720 \
  --width 1280 \
  --seed 4529717 \
  --heatmap-layer-indices 15 16 17 18 \
  --heatmap-timesteps 0 1 2 3 \
  -q 4
```

--------------------------------

### Generate Image with HuggingFace LoRA (CLI)

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/common/README.md

Use a LoRA model directly from HuggingFace by providing its repository ID and scale. This example uses a specific 4-bit model.

```sh
mflux-generate-z-image-turbo \
  --model filipstrand/Z-Image-Turbo-mflux-4bit \
  --steps 9 \
  --prompt "t3chnic4lly vibrant 1960s portrait" \
  --lora-paths renderartist/Technically-Color-Z-Image-Turbo \
  --lora-scales 0.5
```

--------------------------------

### Running ERNIE-Image Training

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/ernie_image/README.md

Execute the training process for ERNIE-Image using a specified configuration file. Ensure the path to the configuration file is correct.

```sh
mflux-train --config /path/to/train_ernie_image_turbo.json
```

--------------------------------

### Generate Image with Quantization (CLI)

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/common/README.md

Use the `--quantize` flag for on-the-fly quantization to reduce memory usage and speed up inference. This option is applied as weights are loaded.

```sh
mflux-generate-z-image-turbo \
  --model z-image-turbo \
  --quantize 8 \
  --steps 9 \
  --prompt "A photo of a dog"
```

--------------------------------

### Install MFLUX for DGX/NVIDIA with Specific Python Version

Source: https://github.com/filipstrand/mflux/blob/main/README.md

Installs MFLUX using uv, specifying Python version 3.13. This is useful for environments like DGX or NVIDIA systems where specific Python versions might be required.

```sh
uv tool install --python 3.13 mflux
```

--------------------------------

### Inspire Prompt from Image with CLI

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/fibo/README.md

Use the mflux-inspire-fibo CLI to extract a structured prompt from an image. Provide the image path, a descriptive prompt, an output file for the JSON prompt, and a seed.

```sh
mflux-inspire-fibo \
    --image-path bird.jpg \
    --prompt "blue and brown bird on brown tree trunk" \
    --output bird_inspired.json \
    --seed 42
```

--------------------------------

### Reload ZSH Shell

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/cli/completions/README.md

After installing completions, execute this command to reload your ZSH shell and enable them.

```bash
exec zsh
```

--------------------------------

### Generate CatVTON Virtual Try-On Image

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/flux/README.md

This command is for CatVTON (Virtual Try-On) functionality. It requires person, mask, and garment images. The prompt should describe the garment and how it should appear on the person, using markers like [IMAGE1] for the garment and [IMAGE2] for the person wearing it.

```bash
mflux-generate-in-context-catvton \
  --person-image "person.png" \
  --person-mask "mask.png" \
  --garment-image "garment.png" \
  --prompt "The pair of images highlights a clothing and its styling on a model, high resolution, 4K, 8K; [IMAGE1] Detailed product shot of a light blue shirt with designer details such as white and pink patterns; [IMAGE2] The *exact* same cloth (the light blue shirt with designer details such as white and pink patterns) is worn by a model in a lifestyle setting." \
  --steps 20 \
  --seed 6269363 \
  --guidance 30 \
  --height 1024 \
  --width 891 \
  -q 8
```

--------------------------------

### Test mflux Completion Generator

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/cli/completions/README.md

Run the mflux completion generator script directly using Python to test its functionality without installing it.

```python
python -m mflux.cli.completions.generator
```

--------------------------------

### Generate Image with Qwen Image Model

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/qwen/README.md

Use the QwenImage model for text-to-image generation. Specify parameters like seed, prompt, negative prompt, steps, width, and height. The model requires downloading weights, with quantization available for smaller sizes.

```bash
--negative-prompt "blurry, low quality, distorted, deformed, ugly, bad anatomy, bad proportions, extra limbs, duplicate, watermark, signature, text, letters, cartoon, anime, painting, drawing, illustration, 3d render, cgi, fast food, unappetizing" \
  --width 1920 \
  --height 816 \
  --steps 30 \
  --seed 42 \
  -q 8
```

```python
from mflux.models.common.config import ModelConfig
from mflux.models.qwen.variants.txt2img.qwen_image import QwenImage

model = QwenImage(
    quantize=8,
    model_config=ModelConfig.qwen_image(),
)
image = model.generate_image(
    seed=42,
    prompt="Professional food photography, gourmet Chinese cuisine, steamed dumplings, colorful vegetables, traditional table setting, restaurant lighting, shallow depth of field, photorealistic, high detail, magazine quality",
    negative_prompt="blurry, low quality, distorted, deformed, ugly, bad anatomy, bad proportions, extra limbs, duplicate, watermark, signature, text, letters, cartoon, anime, painting, drawing, illustration, 3d render, cgi, fast food, unappetizing",
    num_inference_steps=30,
    width=1920,
    height=816,
)
image.save("qwen_food.png")
```

--------------------------------

### Generate Image with Krea 2 Turbo Defaults

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/krea2/README.md

Use this command-line interface to generate a photorealistic image using Krea 2 Turbo with default settings. Weights download automatically on first run.

```sh
mflux-generate-krea2 \
  --prompt "a photograph of a red fox sitting in a sunlit forest clearing, sharp focus, bokeh" \
  --width 1024 \
  --height 1024 \
  --seed 42 \
  --steps 8 \
  -q 8
```

--------------------------------

### IC-Edit Options

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/flux/README.md

Choose between `--instruction` for simple edits or `--prompt` for comprehensive control over image modifications with IC-Edit.

```sh
sh

```

--------------------------------

### Morning Desk Lifestyle Photo Generation

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/ideogram4/README.md

Generates a lifestyle photograph of a morning desk setup. This prompt specifies details about the objects, their placement, and lighting conditions.

```json
{
  "high_level_description": "A lifestyle flat lay photograph of a morning desk setup with coffee, a notebook with MFLUX written on the page, and a fountain pen on walnut wood with soft window light from the left.",
  "compositional_deconstruction": {
    "background": "Walnut wood desk surface filling the tall frame beneath the objects, with soft morning window light entering from the left and gentle shadows across the grain.",
    "elements": [
      {
        "type": "obj",
        "bbox": [160, 300, 400, 700],
        "desc": "White ceramic coffee mug filled with black coffee, handle on the right, sitting upright near the upper center of the desk."
      },
      {
        "type": "obj",
        "bbox": [100, 360, 260, 640],
        "desc": "Round tortoiseshell reading glasses folded closed, lying beside the coffee mug."
      },
      {
        "type": "obj",
        "bbox": [420, 260, 860, 740],
        "desc": "Open cream-page notebook with a black elastic band, lying flat in the lower half of the frame."
      },
      {
        "type": "text",
        "bbox": [480, 380, 560, 680],
        "text": "MFLUX",
        "desc": "MFLUX written in dark fountain-pen ink on the open notebook page in clean uppercase letters."
      },
      {
        "type": "obj",
        "bbox": [560, 380, 760, 620],
        "desc": "Black lacquer fountain pen with a gold nib, resting diagonally across the open notebook beside the writing."
      }
    ]
  }
}
```

--------------------------------

### Generate mflux Completion Script Manually

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/cli/completions/README.md

Manually generate the ZSH completion script for mflux if automatic installation fails. This script will be saved to a file named '_mflux'.

```bash
mflux-completions --print > _mflux
```

--------------------------------

### Run Mflux Training

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/z_image/README.md

Command to execute the mflux training process using a specified configuration file. Replace '/path/to/train_z_image.json' with the actual path to your training configuration.

```sh
mflux-train --config /path/to/train_z_image.json
```

--------------------------------

### Generate Image from Local Model Path (Python API)

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/common/README.md

When initializing a model, set the `model_path` parameter to a local directory containing the model weights. Ensure the directory structure matches HuggingFace standards.

```python
from mflux.models.common.config import ModelConfig
from mflux.models.z_image import ZImageTurbo

model = ZImageTurbo(
    model_config=ModelConfig.z_image_turbo(),
    model_path="/Users/me/models/z-image-turbo",
)
image = model.generate_image(
    seed=42,
    prompt="Luxury food photograph",
    num_inference_steps=9,
)
image.save("luxury_food.png")
```

--------------------------------

### Generate Chinese Street Scene with mflux CLI

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/qwen/README.md

Generate an image of a traditional Chinese street scene using the mflux CLI. This example includes specific Chinese characters in the prompt.

```sh
mflux-generate-qwen \
  --prompt "Traditional Chinese street scene, old neighborhood with shop signs displaying Chinese characters (店铺, 餐厅, 书店), red lanterns, narrow alleys, traditional architecture, bustling street life, natural lighting, photorealistic, high detail, street photography" \
  --negative-prompt "blurry, low quality, distorted, deformed, ugly, bad anatomy, bad proportions, extra limbs, duplicate, watermark, signature, cartoon, anime, painting, drawing, illustration, 3d render, cgi, modern signs, English text only" \
  --width 1920 \
  --height 816 \
  --steps 30 \
  --seed 42 \
  -q 8
```

--------------------------------

### Generate Image from Inspired Prompt with CLI

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/fibo/README.md

Generate an image using the mflux-generate-fibo CLI with a prompt file inspired by an image. Specify output dimensions, generation steps, guidance scale, seed, and quantization level.

```sh
mflux-generate-fibo \
    --prompt-file bird_inspired.json \
    --width 1024 \
    --height 672 \
    --steps 50 \
    --guidance 4.0 \
    --seed 42 \
    -q 8 \
    --output bird_inspired.png
```

--------------------------------

### Generate Image with Quantization (Python API)

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/common/README.md

Instantiate a model with the `quantize` parameter set to reduce memory and improve inference speed. This is applied during model loading.

```python
from mflux.models.common.config import ModelConfig
from mflux.models.z_image import ZImageTurbo

model = ZImageTurbo(quantize=8, model_config=ModelConfig.z_image_turbo())
image = model.generate_image(
    seed=42,
    prompt="A photo of a dog",
    num_inference_steps=9,
)
image.save("dog.png")
```

--------------------------------

### Inspire Prompt from Image with Python API

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/fibo/README.md

Extract a structured prompt from an image using the FiboVLM Python API. Load the image, use the inspire method with a descriptive prompt and seed, and save the resulting JSON prompt.

```python
from pathlib import Path

from mflux.models.fibo_vlm.model.fibo_vlm import FiboVLM
from mflux.models.fibo_vlm.model.util import FiboVLMUtil

vlm = FiboVLM()
image = FiboVLMUtil.load_image(Path("bird.jpg"))
inspired_json = vlm.inspire(
    seed=42,
    image=image,
    prompt="blue and brown bird on brown tree trunk",
)
FiboVLMUtil.save_json_prompt(Path("bird_inspired.json"), inspired_json)
```

--------------------------------

### Ideogram 4 JSON Caption Example

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/ideogram4/README.md

This JSON structure is used for generating images with Ideogram 4, providing detailed descriptions, compositional elements, and text content for specific areas. It's recommended for achieving best results over plain text prompts.

```json
{
  "high_level_description": "A premium vertical natural-history field-guide poster with four mushroom specimens in a 2x2 botanical plate, letterpress feel, and serif typography on warm ivory paper.",
  "compositional_deconstruction": {
    "background": "Warm ivory paper with letterpress texture, registration marks, and margin ticks.",
    "elements": [
      {
        "type": "text",
        "bbox": [42, 120, 98, 880],
        "text": "FUNGI OF THE HIGH MEADOW",
        "desc": "Large serif title in graphite black."
      },
      {
        "type": "text",
        "bbox": [102, 280, 132, 720],
        "text": "Plate 07 • Autumn Survey",
        "desc": "Serif subtitle in chestnut."
      },
      {
        "type": "obj",
        "bbox": [150, 100, 850, 860],
        "desc": "Symmetrical 2x2 botanical plate of four detailed ink mushrooms with specimen arrows: ochre chanterelle top-left, chestnut morel top-right, violet deceiver bottom-left, citrine bolete bottom-right."
      },
      {
        "type": "text",
        "bbox": [460, 140, 490, 440],
        "text": "CHANTERELLE AURORA",
        "desc": "Small caps label."
      },
      {
        "type": "text",
        "bbox": [460, 560, 490, 860],
        "text": "MOREL PINEA",
        "desc": "Small caps label."
      },
      {
        "type": "text",
        "bbox": [830, 140, 860, 500],
        "text": "AMETHYST DECEIVER",
        "desc": "Small caps label."
      },
      {
        "type": "text",
        "bbox": [830, 560, 860, 860],
        "text": "CITRINE BOLETE",
        "desc": "Small caps label."
      },
      {
        "type": "text",
        "bbox": [900, 180, 940, 820],
        "text": "Collected notes, spore marks, and habitat sketches",
        "desc": "Bottom caption in moss green."
      }
    ]
  }
}
```

--------------------------------

### Test mflux Command Completions

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/cli/completions/README.md

Test the shell completion by typing a partial command and pressing TAB.

```bash
mflux-generate --<TAB>
```

--------------------------------

### Generate Image with Krea 2 Turbo using Python API

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/krea2/README.md

This Python code demonstrates how to instantiate and use the Krea2 model for image generation via its API. Ensure model weights are downloaded and accessible.

```python
from mflux.models.common.config import ModelConfig
from mflux.models.krea2 import Krea2

model = Krea2(
    model_config=ModelConfig.krea2(),
    quantize=8,
)
image = model.generate_image(
    seed=42,
    prompt="a photograph of a red fox sitting in a sunlit forest clearing, sharp focus, bokeh",
    num_inference_steps=8,
    width=1024,
    height=1024,
    guidance=1.0,
)
image.save("krea2_fox.png")
```

--------------------------------

### Generate Image with Local LoRA (Python API)

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/common/README.md

Initialize ZImageTurbo with LoRA paths and scales. The model will use these LoRA configurations during image generation.

```python
from mflux.models.common.config import ModelConfig
from mflux.models.z_image import ZImageTurbo

model = ZImageTurbo(
    model_config=ModelConfig.z_image_turbo(),
    lora_paths=["/local/path/to/lora.safetensors"],
    lora_scales=[0.8],
)
image = model.generate_image(
    seed=42,
    prompt="a portrait",
    num_inference_steps=9,
)
image.save("portrait_lora.png")
```

--------------------------------

### Generate Image from HuggingFace Model (CLI)

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/common/README.md

Specify a HuggingFace repository name directly in the `--model` argument to load weights from the Hub. This simplifies using community-shared models.

```sh
mflux-generate-z-image-turbo \
  --model filipstrand/Z-Image-Turbo-mflux-4bit \
  --steps 9 \
  --prompt "A beautiful landscape"
```

--------------------------------

### Python API: Generate Image with Callbacks for Resource Management

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/common/README.md

Configure image generation using the Python API with callbacks for memory and battery saving, and stepwise image output. This provides fine-grained control over resource usage and intermediate results.

```python
from mflux.callbacks.instances.battery_saver import BatterySaver
from mflux.callbacks.instances.memory_saver import MemorySaver
from mflux.callbacks.instances.stepwise_handler import StepwiseHandler
from mflux.models.common.config import ModelConfig
from mflux.models.z_image import ZImageTurbo
from mflux.models.z_image.latent_creator import ZImageLatentCreator

model = ZImageTurbo(model_config=ModelConfig.z_image_turbo())
model.callbacks.register(BatterySaver(battery_percentage_stop_limit=20))
model.callbacks.register(MemorySaver(model=model, keep_transformer=False))
model.callbacks.register(
    StepwiseHandler(
        model=model,
        output_dir="./steps",
        latent_creator=ZImageLatentCreator,
    )
)
image = model.generate_image(
    seed=42,
    prompt="a portrait",
    num_inference_steps=9,
)
image.save("image.png")
```

--------------------------------

### Generate Image from Local Model Path (CLI)

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/common/README.md

Use the `--model` argument with a local directory path to load a model. Specify `--base-model` if the local path requires it for configuration.

```sh
mflux-generate-z-image-turbo \
  --model "/Users/me/models/z-image-turbo" \
  --base-model z-image-turbo \
  --steps 9 \
  --prompt "Luxury food photograph"
```

--------------------------------

### Create Outpainting Canvas and Mask (General Padding)

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/flux/README.md

Use this command to create an expanded canvas and mask for outpainting. The padding format 'top,right,bottom,left' allows for pixel or percentage-based expansion.

```bash
python tools/create_outpaint_image_canvas_and_mask.py \
  /path/to/your/image.jpg \
  --image-outpaint-padding "0,30%,20%,0"
```

--------------------------------

### Generate Image from Text Prompt (Python API)

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/fibo/README.md

This Python code demonstrates generating a structured JSON prompt from text using FiboVLM, saving it, and then using it to generate an image with the FIBO model. Ensure FiboVLM and FIBO are imported.

```python
from pathlib import Path

from mflux.models.common.config import ModelConfig
from mflux.models.fibo.variants.txt2img.fibo import FIBO
from mflux.models.fibo_vlm.model.fibo_vlm import FiboVLM
from mflux.models.fibo_vlm.model.util import FiboVLMUtil

vlm = FiboVLM()
json_prompt = vlm.generate(
    prompt="Three cartoon animal chefs in a colorful bakery kitchen, Pixar style: a bunny with floppy ears wearing a tall white chef hat and pink apron holding a chocolate cake on the left, a raccoon with a striped tail wearing blue oven mitts and a yellow bandana frosting cupcakes in the center, a penguin wearing a red bowtie and checkered apron carrying a tray of golden croissants on the right, warm kitchen lighting with flour dust in air",
    seed=42,
)
FiboVLMUtil.save_json_prompt(Path("animal_bakers.json"), json_prompt)

model = FIBO(model_config=ModelConfig.fibo())
image = model.generate_image(
    seed=42,
    prompt=json_prompt,
    num_inference_steps=50,
    width=1200,
    height=540,
    guidance=4.0,
)
image.save("animal_bakers.png")
```

--------------------------------

### Generate Image with FLUX.1 Krea [dev]

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/flux/README.md

Use this command to generate an image with the FLUX.1 Krea [dev] model. Specify parameters like prompt, steps, seed, quality, and dimensions.

```sh
mflux-generate \
    --model krea-dev \
    --prompt "A photo of a dog" \
    --steps 25 \
    --seed 2674888 \
    -q 8 \
    --height 1024 \
    --width 1024
```

--------------------------------

### Generate Image with Z-Image (Base) CLI

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/z_image/README.md

Use this command to generate images with the base Z-Image model. Specify prompt, dimensions, seed, steps, and guidance scale. Base Z-Image is slower but can be used for training.

```sh
mflux-generate-z-image \
  --prompt "A red fox resting in fresh snow under soft winter light, detailed fur, gentle bokeh, natural color grading." \
  --width 720 \
  --height 1280 \
  --seed 42 \
  --steps 50 \
  --guidance 4
```

--------------------------------

### Generate Image with Low RAM and Stepwise Output

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/common/README.md

Optimize memory usage with the `--low-ram` flag and save intermediate images during generation using `--stepwise-image-output-dir`. This is useful for debugging or analyzing the generation process.

```sh
mflux-generate-z-image-turbo \
  --model z-image-turbo \
  --steps 9 \
  --prompt "a portrait" \
  --low-ram \
  --stepwise-image-output-dir ./steps
```

--------------------------------

### Generate Image with Prompt File (Python API)

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/common/README.md

Read prompt text from a file and pass it to the generate_image method. Ensure the prompt file exists at the specified path.

```python
from pathlib import Path

from mflux.models.common.config import ModelConfig
from mflux.models.z_image import ZImageTurbo

prompt = Path("./prompt.txt").read_text().strip()
model = ZImageTurbo(model_config=ModelConfig.z_image_turbo())
image = model.generate_image(
    seed=42,
    prompt=prompt,
    num_inference_steps=9,
)
image.save("prompt_file.png")
```

--------------------------------

### Generate Image with Prompt File (CLI)

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/common/README.md

Use the --prompt-file argument to specify a text file containing the prompt. This is useful for iterating on prompts without restarting the CLI.

```sh
mflux-generate-z-image-turbo \
  --model z-image-turbo \
  --steps 9 \
  --prompt-file ./prompt.txt
```

--------------------------------

### Inspect Image Metadata with CLI

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/common/README.md

Use the `mflux-info` command-line tool to inspect and display metadata embedded within an image file generated by MFLUX.

```sh
mflux-info ./image.png
```

--------------------------------

### Generate Image with ERNIE-Image-Turbo (CLI)

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/ernie_image/README.md

Use this command-line interface to generate images using the distilled ERNIE-Image-Turbo model. It supports specifying prompts, dimensions, seed, and inference steps.

```shell
mflux-generate-ernie-image-turbo \
  --prompt "Close-up portrait of a barn owl perched on a mossy branch, heart-shaped face, detailed feathers, soft forest bokeh, natural wildlife photography." \
  --width 1024 \
  --height 576 \
  --seed 404 \
  --steps 8 \
  -q 8
```

--------------------------------

### Generate Image with FLUX.2 Klein Base 9B

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/flux2/README.md

Use this command for base (non-distilled) FLUX.2 Klein models, which typically require more steps and allow guidance greater than 1.0. These are noted as potentially slower for general editing but suitable for training.

```sh
mflux-generate-flux2 \
  --model flux2-klein-base-9b \
  --prompt "A red fox resting in fresh snow under soft winter light, detailed fur, gentle bokeh, natural color grading." \
  --steps 50 \
  --guidance 1.5 \
  --seed 640563507 \
  --width 1024 \
  --height 560
```

--------------------------------

### Generate Image from Inspired Prompt with Python API

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/fibo/README.md

Generate an image using the FIBO model in Python with an inspired structured prompt. Load the prompt, initialize the FIBO model with quantization, and call the generate_image method.

```python
from pathlib import Path

from mflux.models.common.config import ModelConfig
from mflux.models.fibo.variants.txt2img.fibo import FIBO
from mflux.models.fibo_vlm.model.util import FiboVLMUtil

structured_prompt = FiboVLMUtil.get_structured_prompt(Path("bird_inspired.json"))
model = FIBO(model_config=ModelConfig.fibo(), quantize=8)
image = model.generate_image(
    seed=42,
    prompt=structured_prompt,
    num_inference_steps=50,
    width=1024,
    height=672,
    guidance=4.0,
)
image.save("bird_inspired.png")
```

--------------------------------

### Generate Image from Refined Prompt with CLI

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/fibo/README.md

Generate an image using the mflux-generate-fibo CLI with a refined JSON prompt file. Specify output dimensions, generation steps, guidance scale, seed, and quantization level.

```sh
mflux-generate-fibo \
    --prompt-file owl_white.json \
    --width 1024 \
    --height 560 \
    --steps 20 \
    --guidance 4.0 \
    --seed 42 \
    --quantize 4 \
    --output owl_white.png
```

--------------------------------

### Run IC-Edit Command

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/flux/README.md

Execute the mflux-generate-in-context-edit command with a reference image and a detailed prompt. Ensure the prompt clearly describes the desired changes, especially regarding color and style.

```bash
mflux-generate-in-context-edit \
  --reference-image "flower.jpg" \
  --prompt "two images of the exact same flower in two different styles: On the left the photo has is in bright colors showing green leaves and a pink flower. On the right, the *exact* same photo (same flower, same leaves, same background, identical etc). but with where everything is black and white except for the flower which is still in color. The content is *exactly* the same between the left and right image, except only for the coloring (black and white for everything except for the colorful flower)" \
  --steps 20 \
  --seed 8570325 \
  --guidance 30 \
  -q 8
```

--------------------------------

### Generate Image from JSON Prompt (Python API)

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/fibo/README.md

This Python code demonstrates loading a structured JSON prompt from a file and using it to generate an image with the FIBO model. Ensure necessary imports are present.

```python
from pathlib import Path

from mflux.models.common.config import ModelConfig
from mflux.models.fibo.variants.txt2img.fibo import FIBO
from mflux.models.fibo_vlm.model.util import FiboVLMUtil

structured_prompt = FiboVLMUtil.get_structured_prompt(Path("animal_bakers.json"))
model = FIBO(model_config=ModelConfig.fibo())
image = model.generate_image(
    seed=42,
    prompt=structured_prompt,
    num_inference_steps=50,
    width=1200,
    height=540,
    guidance=4.0,
)
image.save("animal_bakers.png")
```

--------------------------------

### Perform Image Editing with Qwen Image Edit Model

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/qwen/README.md

Utilize the QwenImageEdit model for natural language image editing. This model supports text instructions to modify images while preserving structure. It requires specifying image paths, a detailed prompt, and generation parameters like steps, guidance, width, and height.

```bash
mflux-generate-qwen-edit \
  --image-paths "dog1.png" "dog2.png" \
  --prompt "Replace the golden retriever (standing outside, holding white rose) in Image 1 with the grey dog from Image 2 (which is standing inside in a studio). The grey dog should hold a red rose in its mouth and stand outside in the same position as the golden retriever. Maintain the outside environment, background, lighting, and all surroundings completely unchanged." \
  --steps 30 \
  --guidance 2.5 \
  --width 624 \
  --height 1024
```

```python
from mflux.models.common.config import ModelConfig
from mflux.models.qwen.variants.edit.qwen_image_edit import QwenImageEdit

model = QwenImageEdit(model_config=ModelConfig.qwen_image_edit())
image = model.generate_image(
    seed=42,
    prompt="Replace the golden retriever (standing outside, holding white rose) in Image 1 with the grey dog from Image 2 (which is standing inside in a studio). The grey dog should hold a red rose in its mouth and stand outside in the same position as the golden retriever. Maintain the outside environment, background, lighting, and all surroundings completely unchanged.",
    image_paths=["dog1.png", "dog2.png"],
    num_inference_steps=30,
    guidance=2.5,
    width=624,
    height=1024,
)
image.save("qwen_edit_dogs.png")
```

--------------------------------

### In-Context Image Editing with Instructions

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/flux/README.md

Use mflux-generate-in-context-edit with a reference image and a clear instruction to modify the image. This is the recommended method for most editing tasks.

```bash
mflux-generate-in-context-edit \
  --reference-image "photo.jpg" \
  --instruction "remove the glasses"
```

--------------------------------

### Generate Image with FIBO Lite CLI

Source: https://github.com/filipstrand/mflux/blob/main/src/mflux/models/fibo/README.md

Use the mflux-generate-fibo command-line tool to generate images with the FIBO Lite model. Specify the model, prompt, number of steps, and a seed for reproducibility. FIBO Lite is optimized for speed, requiring fewer steps and a guidance scale of 1.0.

```sh
mflux-generate-fibo \
  --model fibo-lite \
  --prompt "A tiny watercolor robot in a garden" \
  --steps 8 \
  --seed 42
```