README.md

---
title: MOSS Image
emoji: 🖼
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.30.0
python_version: "3.12"
app_file: app.py
pinned: false
license: apache-2.0
short_description: Official demo of MOSS-Image.
---

# MOSS-Image Demo

<p align="center">
  <a href="https://huggingface.co/OpenMOSS-Team/MOSS-Image-Base"><img alt="Hugging Face · MOSS-Image-Base" src="https://img.shields.io/badge/🤗%20Hugging%20Face-MOSS--Image--Base-ffc107?style=flat-square"></a>
  &nbsp;
  <a href="https://huggingface.co/OpenMOSS-Team/MOSS-Image-SFT"><img alt="Hugging Face · MOSS-Image-SFT" src="https://img.shields.io/badge/🤗%20Hugging%20Face-MOSS--Image--SFT-ffc107?style=flat-square"></a>
  &nbsp;
  <a href="https://modelscope.cn/models/openmoss/MOSS-Image-Base"><img alt="ModelScope · MOSS-Image-Base" src="assets/modelscope-base-badge.svg"></a>
  &nbsp;
  <a href="https://modelscope.cn/models/openmoss/MOSS-Image-SFT"><img alt="ModelScope · MOSS-Image-SFT" src="assets/modelscope-sft-badge.svg"></a>
  &nbsp;
  <a href="https://github.com/OpenMOSS/MOSS-Image"><img alt="GitHub" src="https://img.shields.io/badge/GitHub-Code-181717?style=flat-square&amp;logo=github&amp;logoColor=white"></a>
  &nbsp;
  <a href="https://openmoss.github.io/MOSS-Image/"><img alt="Homepage" src="https://img.shields.io/badge/🌐%20Project-Homepage-2563eb?style=flat-square"></a>
  &nbsp;
  <a href="https://github.com/OpenMOSS/MOSS-Image/blob/main/paper/MOSS_Image_Technical_Report.pdf"><img alt="Technical Report" src="https://img.shields.io/badge/📄%20Paper-Technical_Report-b31b1b?style=flat-square"></a>
  &nbsp;
  <a href="https://x.com/Open_MOSS"><img alt="Follow OpenMOSS on X" src="https://img.shields.io/badge/Follow-OpenMOSS-000000?style=flat-square&amp;logo=x&amp;logoColor=white"></a>
  &nbsp;
  <a href="https://qm.qq.com/q/hphM7VhaDu"><img alt="MOSS-Image QQ 交流群：755535143" src="https://img.shields.io/badge/QQ-755535143-12B7F5?style=flat-square&amp;logo=qq&amp;logoColor=white"></a>
  &nbsp;
  <a href="https://applink.feishu.cn/client/chat/chatter/add_by_link?link_token=7a3m2007-815f-409b-9c3d-a4129f5c058e"><img alt="MOSS-Builders Feishu Community" src="assets/feishu-builders-badge.svg"></a>
  &nbsp;
  <a href="https://discord.gg/nXFWEyvbb"><img alt="MOSS-Image Discord Community" src="https://img.shields.io/badge/Discord-Community-5865F2?style=flat-square&amp;logo=discord&amp;logoColor=white"></a>
</p>

Gradio interface for [MOSS-Image](https://github.com/OpenMOSS/MOSS-Image),
including resolution and aspect-ratio presets, sampling controls, a selectable
example gallery, advanced guidance controls, and live example/default-prompt updates.

## Model loading

The Space preloads **MOSS-Image-Base** and **MOSS-Image-SFT** with
`snapshot_download(repo_id, revision=resolved_commit)`, followed by
`MOSSImagePipeline.from_pretrained(snapshot_path, local_files_only=True, ...)`.
The Space explicitly loads its bundled pipeline, transformer and scheduler classes
from `pipeline_moss_image.py` for the ZeroGPU AOT lifecycle. The bundled inference
implementation follows the current Base pipeline, including negative-branch skipping
and standard SLG. Progress is reported using the same bridge as the standalone app.
Weights are downloaded into the Hugging Face cache; no local model directory
or model weights in this repository are required.

Select **MOSS-Image-Base** or **MOSS-Image-SFT** in the Model dropdown before
clicking Generate. Base is selected by default. The optional `MOSS_MODEL_ID`
Space variable changes this initial selection.

Both transformers are loaded at startup. The text encoder, tokenizer and VAE
are each shared only when their Hub file hashes match at the resolved revisions.
Components that differ, such as model-specific VAEs, are loaded separately. Each model retains its own
scheduler, prompt cache and revision metadata. Generation requests run serially;
changing the dropdown does not change an already submitted request.

While the model repositories are private, configure an `HF_TOKEN` **Space secret**
with read access to both models. Do not put a token in source files or
ordinary Space variables. Local development uses the same environment variable
or your cached Hugging Face login.

## ZeroGPU

Both pipelines are loaded and placed on CUDA before the UI starts. Generation runs
under `@spaces.GPU(duration=80)`. At startup, a separate GPU allocation exports
and AOT-compiles the repeated DiT and text-projection blocks with dynamic sequence
lengths. Both models reuse the compiled graphs with their own weights. Compilation
is validated against eager block outputs before the UI starts. This uses ZeroGPU
AOTInductor support, not runtime `torch.compile`; GPU residency is fixed.
Set the Space variable `MOSS_AOTI=0` to run the eager baseline. Compilation happens
once per container start and is not part of image generation latency.
The 80-second budget is scaled to 120 seconds by the current RTX PRO 6000
ZeroGPU SDK configuration; it is not a measured latency guarantee.
Large images or batches may require more time or memory than the allocation allows.

Outputs and version-2 parameter JSON files are stored under `outputs/gradio/`. Records
include the model repository and resolved revision, actual seed, sampling
parameters, component configuration hashes, execution backend, and software versions. Space storage
is ephemeral; save generated images you want to keep.

## Local development

```bash
pip install -r requirements.txt
python app.py
```

To inspect the UI without downloading weights or allocating a GPU:

```bash
python app.py --preview --port 7861
```

The UI and size presets follow the MOSS-Image development repository (main at
`8a3223c`). CFG defaults to 3; advanced settings contain CFG, shift and the
Off / Negative-branch skipping / Standard SLG modes. Aspect ratios span 1:8–8:1.
Examples restore their prompts, sampling settings and seed; unknown seeds become
random (-1). Example files and default prompts refresh every two seconds.

ZeroGPU keeps the two official model choices, startup preloading, matching-component
sharing and AOT compilation. Memory mode and runtime Compile DiT controls are not
shown because GPU residency and compilation are managed at startup. The generation
API returns the gallery and status, matching the standalone interface.

## Licenses

Model weights use Apache-2.0. Bundled pipeline code retains its BSD 3-Clause
license in [LICENSE-CODE](LICENSE-CODE). See [NOTICE.md](NOTICE.md) for component
attribution and the licenses in `third_party/`.