README.md

---
license: unknown
pipeline_tag: text-to-image
tags:
  - text-to-image
  - image-to-image
  - image-editing
  - multi-reference
  - distilled
  - turbo
---

# Mage-Flow Turbo + Edit Turbo

4-step photographic text-to-image (**≈3 s** per 1024² image on an RTX 5090)
and a companion instruction-editing model that takes up to **three**
reference images.

> **What this repo is:** the Mage-Flow turbo and turbo-edit transformers, a
> shared Qwen2.5-VL text encoder and VAE — weights only, not a retrain. The
> settings below are the values these weights are actually run with day to
> day.

---

## Samples — `mage-flow-turbo` (txt2img)

Four steps, guidance 1.0. Photorealism is this model's strength.

<table>
<tr><td><img src="https://huggingface.co/ChrisColeTech/Mage-Flow/resolve/main/samples/apple.png" width="380" alt="prompt: a red apple on a rustic wooden table beside a window, soft daylight, fine skin texture and wood grain, studio photograph, sharp focus — 1024×1024, 4 steps, guidance 1.0, seed 12345"></td><td><img src="https://huggingface.co/ChrisColeTech/Mage-Flow/resolve/main/samples/portrait.png" width="380" alt="prompt: portrait of an older fisherman with a weathered face, natural window light, shallow depth of field, photorealistic — 1024×1024, 4 steps, guidance 1.0, seed 99"></td></tr>
<tr><td><sub>**prompt:** `a red apple on a rustic wooden table beside a window, soft daylight, fine skin texture and wood grain, studio photograph, sharp focus` — 1024×1024, 4 steps, guidance 1.0, seed 12345</sub></td><td><sub>**prompt:** `portrait of an older fisherman with a weathered face, natural window light, shallow depth of field, photorealistic` — 1024×1024, 4 steps, guidance 1.0, seed 99</sub></td></tr>
<tr><td><img src="https://huggingface.co/ChrisColeTech/Mage-Flow/resolve/main/samples/street.png" width="380" alt="prompt: a rain-slicked Tokyo street at night, neon signs reflecting in puddles, cinematic, 35mm photograph — 1024×1024, 4 steps, guidance 1.0, seed 1234"></td><td></td></tr>
<tr><td><sub>**prompt:** `a rain-slicked Tokyo street at night, neon signs reflecting in puddles, cinematic, 35mm photograph` — 1024×1024, 4 steps, guidance 1.0, seed 1234</sub></td><td></td></tr>
</table>

---

## Editing — `mage-flow-edit-turbo` (img2img)

Plain-language instructions against a reference image. Identity, pose,
lighting and camera are preserved; only what the instruction names changes.

<table>
<tr><td><img src="https://huggingface.co/ChrisColeTech/Mage-Flow/resolve/main/samples/portrait.png" width="250" alt="reference"></td><td><img src="https://huggingface.co/ChrisColeTech/Mage-Flow/resolve/main/samples/edit-hat.png" width="250" alt="edit: put a brown flat cap on his head"></td><td><img src="https://huggingface.co/ChrisColeTech/Mage-Flow/resolve/main/samples/edit-beach.png" width="250" alt="edit: change the background to a sunny beach"></td></tr>
<tr><td><sub>**reference** — the seed-99 portrait above</sub></td><td><sub>**instruction:** `put a brown flat cap on his head` — 4 steps, seed 7 (≈88 s)</sub></td><td><sub>**instruction:** `change the background to a sunny beach with the ocean behind him` — 4 steps, seed 7 (≈60 s)</sub></td></tr>
</table>

Both edits keep the subject essentially pixel-identical — same skin detail,
same jacket, same catchlights — while adding an object in one case and
replacing the entire environment in the other. Up to **three** reference
images may be supplied together (subject, style, context).

## Recommended settings

Values these builds are run with in practice.

| Parameter | `mage-flow-turbo` | `mage-flow-edit-turbo` | Meaning |
|---|---|---|---|
| `width` × `height` | `1024` × `1024` | follows the reference | Output size |
| `steps` | `4` | `4` | Denoising steps |
| `guidance` | `1.0` | `1.0` | Distilled — CFG is not used |
| `max_size` | — | `1024` | Longest edge the reference is fitted to |
| `vl_condition_long_edge` | — | `384` | Resolution the VL encoder sees the reference at |

**Supported modes:** `txt2img` (turbo), `img2img` / instruction editing (edit-turbo, 1–3 references)

### Notes and gotchas

- **Four steps is correct.** Both variants are step-distilled at guidance 1.0;
  raising either is not the lever for quality.
- **Editing costs far more than generating** — ≈60–90 s versus ≈3 s, because
  the reference must be encoded through the VL tower before denoising begins.
  That asymmetry is inherent to the architecture, not a misconfiguration.
- **Write edits as instructions, not descriptions** — `put a brown flat cap on
  his head`, not `a man wearing a brown flat cap`.
- **`torchvision` is a hard dependency** of the Mage-Flow pipeline (the VL
  image preprocessing path) even though the rest of this stack does not need
  it. Install the build matching your torch (`torchvision==0.28.0` for torch
  2.13.0+cu130) or loading fails with `ModuleNotFoundError`.
- **Three transformers ship here**: `base` (30 steps, guidance 5.0 — the
  undistilled model), `turbo` and `turbo-edit` (4 steps, guidance 1.0). The
  samples on this card are from the two turbo variants; the base transformer
  is included for anyone who wants the slower, higher-guidance path.
- Each transformer directory is self-contained — download only the variant you
  intend to run (8.2 GB each) plus the shared encoder, VAE and scheduler.

---

## Layout

Components ship as separate directories under `split/`: one transformer
directory per variant (`turbo`, `turbo-edit`), plus the shared text encoder,
VAE and scheduler config. Loaders that accept a diffusers-style component tree
can consume this directly.

---

## Files

| Path | Size | Role |
|---|---|---|
| `split/transformer/turbo/diffusion_pytorch_model.safetensors` | 8.23 GB | txt2img transformer (4-step distilled) — **the tier these settings were measured on** |
| `split/transformer/turbo-edit/diffusion_pytorch_model.safetensors` | 8.23 GB | instruction-editing transformer (4-step distilled) |
| `split/transformer/base/diffusion_pytorch_model.safetensors` | 8.23 GB | undistilled transformer (30 steps, guidance 5.0) |
| `split/text_encoder/` | 8.88 GB | Qwen2.5-VL text/vision encoder (2 shards) |
| `split/vae/diffusion_pytorch_model.safetensors` | 345 MB | VAE |
| `split/scheduler/scheduler_config.json` | 169 B | scheduler config |

---

## Provenance

- **Upstream base model:** Mage-Flow (turbo and turbo-edit distillations)
- **This build:** redistributed as a split component tree with the shared encoder and VAE alongside. Weights are not retrained here.
- **License:** left as `unknown` in this repo's metadata. Refer to the upstream model's license for redistribution and commercial-use terms.