| --- |
| license: mit |
| base_model: HiDream-ai/HiDream-O1-Image-Dev |
| tags: |
| - mlx |
| - mlx-vlm |
| - hidream |
| - text-to-image |
| - apple-silicon |
| - quantized |
| - q8 |
| language: |
| - en |
| pipeline_tag: text-to-image |
| library_name: mlx |
| inference: false |
| authors: |
| - Mrbizarro |
| --- |
| |
| # HiDream-O1-Image-Dev — MLX Q8 (Apple Silicon) |
|
|
| > Ported by **[Mrbizarro](https://huggingface.co/Mrbizarro)** · MIT licensed · published to mlx-community |
|
|
| ## 🎛️ Run it one-click in **[Phosphene](https://github.com/mrbizarro/phosphene)** |
|
|
| Phosphene is a free local generative-video panel for Apple Silicon. HiDream is wired into its Image Studio. **[Install Pinokio](https://pinokio.computer)**, then in Pinokio install [Phosphene](https://github.com/mrbizarro/phosphene). Note: Phosphene's HiDream integration uses BF16 by default since **edit requires BF16** — this Q8 repo is for text-to-image-only workflows that want a deterministic memory upper bound. |
|
|
| --- |
|
|
| An 8-bit quantized MLX port of [HiDream-ai/HiDream-O1-Image-Dev](https://huggingface.co/HiDream-ai/HiDream-O1-Image-Dev). |
|
|
| **⚠ Q8 does NOT support edit / multi-ref.** Per-group dequantization noise compounds against reference-image features in attention and produces degenerate output. For edit / multi-reference workflows use the [BF16 sibling repo](https://huggingface.co/mlx-community/HiDream-O1-Image-Dev-mlx-bf16) instead. |
|
|
| ## Sibling repos |
|
|
| - 🟢 **[BF16 (full precision)](https://huggingface.co/mlx-community/HiDream-O1-Image-Dev-mlx-bf16)** — 17.5 GB, ~16 GB RAM, clean across all dimensions. **Use this when in doubt.** |
| - 🟡 [Q6](https://huggingface.co/mlx-community/HiDream-O1-Image-Dev-mlx-q6) — 8 GB, ~8.5 GB RAM, fastest. Same artifact behaviour as Q8. |
| - 🟡 **Q8 (this repo)** — 10 GB, ~11.5 GB RAM, balanced. **Best at square 2048×2048 or 1024×1024.** Visible 32-pixel patch grid in flat regions at non-square dims. |
|
|
| ## When to use Q8 |
|
|
| - ✅ **Square 1024×1024 or 2048×2048** — clean output, less RAM than BF16 |
| - ✅ When you want a deterministic memory upper bound (Q8 doesn't depend on activation distribution) |
| - ❌ **Non-square dims (1440×2560, 3104×1312, etc)** — visible 32-pixel patch grid in skies, walls, water → use BF16 |
| - ⚠ Q8 is **not faster than Q6** here — both are bandwidth-bound on this hardware. Pick Q8 only if you need its slightly tighter quality margin at square dims. |
|
|
| ## What's in this repo |
|
|
| - `model.safetensors` — Q8 quantized backbone (10 GB) |
| - `extras/custom_heads.safetensors` — diffusion-side heads (75 MB, BF16) |
| - `config.json` (with `quantization: {bits: 8, group_size: 64}` so mlx-vlm wraps `Linear → QuantizedLinear` correctly) |
| - Tokenizer + processor configs |
|
|
| ## Code |
|
|
| Inference scripts are in the [BF16 sibling repo](https://huggingface.co/mlx-community/HiDream-O1-Image-Dev-mlx-bf16) under `scripts/hidream_o1/`. Clone that for code, this for weights only. |
|
|
| ## Quick start |
|
|
| ```bash |
| # Get the code from the BF16 sibling |
| hf download mlx-community/HiDream-O1-Image-Dev-mlx-bf16 --local-dir hidream-o1-mlx \ |
| --include "scripts/*" --include "*.md" --include "*.txt" --include "*.gitattributes" |
| cd hidream-o1-mlx |
| uv venv --python 3.11 && uv pip install -r requirements.txt |
| |
| # Get the Q8 weights |
| hf download mlx-community/HiDream-O1-Image-Dev-mlx-q8 --local-dir mlx_models/hidream-o1-dev-q8 |
| |
| # Run (square dims only for clean output) |
| .venv/bin/python scripts/hidream_o1/generate_hidream_o1_mlx.py \ |
| --model-path mlx_models/hidream-o1-dev-q8 \ |
| --prompt "your prompt here" \ |
| --width 2048 --height 2048 \ |
| --output out.png |
| ``` |
|
|
| ## Performance |
|
|
| | Resolution | Per step | Total (28 steps) | Peak RAM | Quality | |
| |---|---|---|---|---| |
| | 1024×1024 | 2.36 s | 67 s | 11.5 GB | ✅ clean | |
| | 2048×2048 | 6.68 s | 187 s | 11.5 GB | ✅ clean | |
| | 1440×2560 (non-square) | ~4.5 s | ~127 s | ~10 GB | ⚠ patch grid visible | |
|
|
| ## License |
|
|
| MIT — see the [BF16 repo](https://huggingface.co/mlx-community/HiDream-O1-Image-Dev-mlx-bf16) for the full LICENSE file and acknowledgements. |
|
|
