# MOSS-Image-Base + DMD2 8-step text-to-image

This service turns a text prompt into a 1024x1024 PNG. MOSS-Image-Base is OpenMOSS's base text-to-image checkpoint (Apache-2.0); this variant adds data-archetype's 8-step DMD2 LoRA, distilled on Base by distribution matching, applied unmerged through forward hooks. It uses the one sampler the LoRA was trained for (clean estimate, then re-noise with fresh noise; ComfyUI's lcm) over 8 steps at flow shift 4.4817, CFG 1 with no negative branch. It runs through diffusers with the checkpoint's own pipeline_moss_image.py (trust_remote_code) and Qwen3.5-9B as the text encoder, on one GPU, with gx10's moss_image_server.py. Generation settings are
fixed by this capsule (`size` "1024x1024", `num_inference_steps` 8, `guidance_scale` 1.0, `shift` 4.4817, `sampler` "fresh-noise", `lora` "moss_image_base_dmd2"). You send a prompt and, optionally, a seed.

Base URL: `{{BASE_URL}}`

## Routes

### `POST /v1/images/generations`
OpenAI-style image generation. Returns one image as base64 PNG.

```bash
curl -s {{BASE_URL}}/v1/images/generations {{AUTH}} \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a lighthouse at sunset", "seed": 42}' \
  | python3 -c 'import sys,json,base64; d=json.load(sys.stdin); open("out.png","wb").write(base64.b64decode(d["data"][0]["b64_json"])); print(d["params_used"])'
```

Request fields:
- `prompt` (string, required): what to draw.
- `seed` (integer >= 0, optional): the random seed. The same prompt and seed give the same
  image. Leave it out for a random one.

Also accepted, for stock OpenAI clients: `model` (any string), `n` (must be 1),
`response_format` (must be `"b64_json"`), `user`, and `size` if it is `"1024x1024"`. Any other
field, or another value for a fixed one, is rejected with `400`.

The response is `{"created": ..., "data": [{"b64_json": "<PNG, base64>"}], "params_used": {...}}`.

The OpenAI Python SDK works too:
```python
from openai import OpenAI
client = OpenAI(base_url="{{BASE_URL}}/v1", api_key="unused")
r = client.images.generate(model="moss-image-base-dmd2", prompt="a lighthouse at sunset",
                           response_format="b64_json", extra_body={"seed": 7})
```

### `GET /v1/config`
The server's settings and what they mean.

### `GET /status`
Where the service is in its start-up: `phase` is one of `building`, `downloading`,
`starting`, `loading`, `ready`, `error`, with `eta_seconds`.

## Timings and concurrency
- First start: builds a container image and downloads about 31 GB of weights.
  After that, loading takes about LOADTIME (budgeted at 600 s).
- Each image takes about IMGTIME on a DGX Spark (GB10).
- Send requests one at a time, and allow at least IMGTIMEOUT per request in your client timeout.

## Errors
- `503` with `Retry-After` while the service is still starting.
- `400`: a field was rejected; the body's `error` says which and why.
- `422`: `prompt` missing or a field of the wrong type.
- `5xx` otherwise: retry once, then check `GET /status`.