{
  "hf_id": "OpenMOSS-Team/MOSS-Image-Base",
  "meta": {
    "title": "MOSS-Image",
    "slug": "moss-image",
    "provider": "OpenMOSS",
    "description": "Serve MOSS-Image-Base and MOSS-Image-SFT with vLLM-Omni for text-to-image generation, Chinese text rendering, and JSON layout prompts.",
    "date_added": "2026-10-16",
    "date_updated": "2026-10-16",
    "tasks": [
      "omni"
    ],
    "hardware": {
      "rtx_pro_6000": "supported",
      "rtx_pro_6000_8x": "supported"
    }
  },
  "model": {
    "model_id": "OpenMOSS-Team/MOSS-Image-Base",
    "min_vllm_version": "0.31.0",
    "docker_image": {
      "cu130": "vllm/vllm-omni:mosimage",
      "cu129": "vllm/vllm-omni:mosimage-cu129"
    },
    "architecture": "dense",
    "parameter_count": "5B",
    "active_parameters": "5B",
    "context_length": 0,
    "base_args": [
      "--enforce-eager"
    ],
    "base_env": {},
    "install": {
      "docker": {
        "command": "docker pull vllm/vllm-omni:mosimage",
        "note": "MOSS-Image preview images with vLLM-Omni PR #8926. Choose CUDA 13.0 or CUDA 12.9 for your host driver."
      }
    }
  },
  "features": {},
  "opt_in_features": [],
  "variants": {
    "default": {
      "label": "Base",
      "precision": "bf16",
      "vram_minimum_gb": 33,
      "description": "MOSS-Image-Base; BF16 DiT/text encoder and FP32 VAE. The memory estimate is for batch 1.",
      "supported_hardware": [
        "h100",
        "h200",
        "b200",
        "gb200",
        "b300",
        "gb300",
        "rtx_pro_6000",
        "rtx_pro_6000_8x"
      ],
      "hardware_overrides": {
        "h100": {
          "docker_serve_command": "vllm serve"
        },
        "h200": {
          "docker_serve_command": "vllm serve"
        },
        "b200": {
          "docker_serve_command": "vllm serve"
        },
        "gb200": {
          "docker_serve_command": "vllm serve"
        },
        "b300": {
          "docker_serve_command": "vllm serve"
        },
        "gb300": {
          "docker_serve_command": "vllm serve"
        },
        "rtx_pro_6000": {
          "docker_serve_command": "vllm serve"
        },
        "rtx_pro_6000_8x": {
          "docker_serve_command": "vllm serve"
        }
      }
    },
    "sft": {
      "label": "SFT",
      "model_id": "OpenMOSS-Team/MOSS-Image-SFT",
      "precision": "bf16",
      "vram_minimum_gb": 33,
      "description": "Supervised fine-tune with the same architecture and pipeline.",
      "supported_hardware": [
        "h100",
        "h200",
        "b200",
        "gb200",
        "b300",
        "gb300",
        "rtx_pro_6000",
        "rtx_pro_6000_8x"
      ],
      "hardware_overrides": {
        "h100": {
          "docker_serve_command": "vllm serve"
        },
        "h200": {
          "docker_serve_command": "vllm serve"
        },
        "b200": {
          "docker_serve_command": "vllm serve"
        },
        "gb200": {
          "docker_serve_command": "vllm serve"
        },
        "b300": {
          "docker_serve_command": "vllm serve"
        },
        "gb300": {
          "docker_serve_command": "vllm serve"
        },
        "rtx_pro_6000": {
          "docker_serve_command": "vllm serve"
        },
        "rtx_pro_6000_8x": {
          "docker_serve_command": "vllm serve"
        }
      }
    }
  },
  "hardware_overrides": {},
  "omni": {
    "port": 8000,
    "variant_label": "Checkpoint",
    "variant_hint": "Base and SFT use the same serving command and sampling parameters.",
    "tasks": [
      {
        "id": "t2i",
        "description": "1024x1024, 50 Euler steps, CFG 3, shift 5, negative-branch layer skipping at index 22.",
        "curl": "curl --fail-with-body -sS http://localhost:8000/v1/images/generations \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"prompt\": \"A sunlit kitchen with a mint-green refrigerator beside a wooden counter. On the refrigerator, a yellow note has three clearly handwritten Chinese lines:\\n记得买牛奶和鸡蛋！\\n牛奶两盒，鸡蛋一打。\\n顺便带一袋面包。\",\n    \"size\": \"1024x1024\",\n    \"n\": 1,\n    \"num_inference_steps\": 50,\n    \"guidance_scale\": 3.0,\n    \"flow_shift\": 5.0,\n    \"seed\": 0,\n    \"negative_prompt\": \"nsfw, worst quality, bad anatomy, watermark, jpeg artifact\",\n    \"response_format\": \"b64_json\",\n    \"extra_params\": {\n      \"uncond_skip_layers\": [22],\n      \"slg_start\": 0.01,\n      \"slg_stop\": 1.0\n    }\n  }' -o response.json && \\\npython3 -c 'import base64,json,pathlib; r=json.loads(pathlib.Path(\"response.json\").read_text()); pathlib.Path(\"moss-image.png\").write_bytes(base64.b64decode(r[\"data\"][0][\"b64_json\"]))'\n",
        "benchmark": "cat > request.json <<'JSON'\n{\n  \"prompt\": \"A sunlit kitchen with a mint-green refrigerator beside a wooden counter. On the refrigerator, a yellow note has three clearly handwritten Chinese lines:\\n记得买牛奶和鸡蛋！\\n牛奶两盒，鸡蛋一打。\\n顺便带一袋面包。\",\n  \"size\": \"1024x1024\",\n  \"n\": 1,\n  \"num_inference_steps\": 50,\n  \"guidance_scale\": 3.0,\n  \"flow_shift\": 5.0,\n  \"seed\": 0,\n  \"negative_prompt\": \"nsfw, worst quality, bad anatomy, watermark, jpeg artifact\",\n  \"response_format\": \"b64_json\",\n  \"extra_params\": {\n    \"uncond_skip_layers\": [22],\n    \"slg_start\": 0.01,\n    \"slg_stop\": 1.0\n  }\n}\nJSON\n# Warm up, then time one image-generation request.\ncurl --fail-with-body -sS http://localhost:8000/v1/images/generations \\\n  -H 'Content-Type: application/json' --data-binary @request.json -o /dev/null && \\\ntime curl --fail-with-body -sS http://localhost:8000/v1/images/generations \\\n  -H 'Content-Type: application/json' --data-binary @request.json -o /dev/null\n"
      }
    ]
  },
  "guide": "## Overview\n\nMOSS-Image supports natural-language prompts, Chinese and English text rendering,\nand structured JSON layouts. This recipe serves\n[MOSS-Image-Base](https://huggingface.co/OpenMOSS-Team/MOSS-Image-Base) and\n[MOSS-Image-SFT](https://huggingface.co/OpenMOSS-Team/MOSS-Image-SFT)\nthrough vLLM-Omni's `/v1/images/generations` API.\n\nMOSS-Image is a 5B diffusion transformer paired with a Qwen3.5 text encoder\nand a FLUX.2 VAE. DiT and text-encoder weights use BF16;\nthe VAE, noise, guidance arithmetic, and Euler updates use FP32.\n\n## Choose a Docker image\n\nInstall Docker and the NVIDIA Container Toolkit on a Linux GPU host.\n\n| Image | CUDA runtime | Suggested Linux driver |\n| --- | --- | --- |\n| `vllm/vllm-omni:mosimage` | 13.0.2 | R580 or newer |\n| `vllm/vllm-omni:mosimage-cu129` | 12.9.1 | 575.57.08 or newer |\n\nThe container supplies CUDA libraries; a separate host CUDA Toolkit installation\nis not required.\nSee NVIDIA's [driver compatibility table](https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#cuda-driver).\n\nUse image builds containing the `MOSSImagePipeline` registration from\n[vLLM-Omni PR #8926](https://github.com/vllm-project/vllm-omni/pull/8926).\nThe pipeline is detected automatically for both Base and SFT checkpoints.\n\n## Start a single-GPU server\n\n```bash\nexport IMAGE=vllm/vllm-omni:mosimage\n# For CUDA 12.9: export IMAGE=vllm/vllm-omni:mosimage-cu129\nexport MODEL=OpenMOSS-Team/MOSS-Image-Base\n# For SFT: export MODEL=OpenMOSS-Team/MOSS-Image-SFT\n\ndocker pull \"$IMAGE\"\ndocker run --rm --name moss-image \\\n  --gpus 'device=0' --ipc=host \\\n  -p 8000:8000 \\\n  -v \"$HOME/.cache/huggingface:/root/.cache/huggingface\" \\\n  -e HF_TOKEN \\\n  \"$IMAGE\" \\\n  vllm serve \"$MODEL\" --omni \\\n    --enforce-eager \\\n    --port 8000\n```\n\n`-e HF_TOKEN` forwards an existing host token if one is set. For an existing\nHugging Face cache, replace the host side of the mount with its cache root.\nFor a standalone model directory, mount it with `-v /path/to/model:/model:ro`,\nuse `vllm serve /model`, and add `--served-model-name \"$MODEL\"`.\n\nThese images have no default entrypoint: include `vllm serve` after the image\nname. Wait for startup to finish, then check the server from another terminal:\n\n```bash\ncurl --fail-with-body -sS http://localhost:8000/health\ncurl --fail-with-body -sS http://localhost:8000/v1/models\n```\n\n## Inference Parameters\n\nMOSS-Image-Base has no post-training or CFG distillation, preserving its training\ninformation for community adaptation such as LoRA. Inference settings therefore\nmatter for image quality. The official\n[Inference Parameters guide](https://github.com/OpenMOSS/MOSS-Image/blob/main/USERGUIDE.md#inference-parameters)\n([中文](https://github.com/OpenMOSS/MOSS-Image/blob/main/USERGUIDE_ZH.md#推理参数配置))\nrecommends:\n\n| Parameter | Official guidance |\n| --- | --- |\n| Resolution (`size`) | Target 1M, 1.5M, or 2M total pixels. The model also supports extrapolation from 0.25M (512 × 512) to 4M (2048 × 2048). |\n| Aspect ratio | Any ratio; both dimensions must be positive multiples of 16. |\n| Steps (`num_inference_steps`) | Use at least 50 for best quality. |\n| CFG (`guidance_scale`) | Default 3.0; recommended range 3.0–6.0. Long prompts generally work at 3.0; increase it as needed for shorter prompts. |\n| Shift (`flow_shift`) | Default 5.0. |\n| Sampler | Euler is recommended. |\n\nThe guide describes two forms of **Skip Layer Guidance (SLG)**:\n\n- **Standard SLG:** use scale 3 over the 0.01–1.0 sampling interval.\n- **Two-pass sampling SLG:** the recommended `uncond skip` mode skips layer 22\n  (zero-based) in the negative branch. Layers 24 and 26 are also useful alternatives.\n\nThe authors report that disabling SLG can increase realism while degrading details.\n\nIn vLLM-Omni, SLG options belong in `extra_params`. Standard SLG uses `slg_layers`\nand `slg_scale`; uncond skip uses `uncond_skip_layers` without requiring\n`slg_scale`. Both use `slg_start` and `slg_stop` to select the sampling interval.\n\n## Generate an image\n\nThis example uses 1024 × 1024, 50 steps, CFG 3.0, shift 5.0, and seed 0, with\n`uncond_skip_layers=[22]` active over `slg_start=0.01` to `slg_stop=1.0`.\n\nNatural-language descriptions, tag lists, and JSON layouts are supported.\nEnglish is recommended for scene descriptions; keep visible Chinese text in\nChinese and insert explicit line breaks to control its layout. This kitchen\nexample follows the guide's approach to multilingual text rendering:\n\n```bash\ncat > request.json <<'JSON'\n{\n  \"prompt\": \"A sunlit kitchen with a mint-green refrigerator beside a wooden counter. On the refrigerator, a yellow note has three clearly handwritten Chinese lines:\\n记得买牛奶和鸡蛋！\\n牛奶两盒，鸡蛋一打。\\n顺便带一袋面包。\",\n  \"size\": \"1024x1024\",\n  \"n\": 1,\n  \"num_inference_steps\": 50,\n  \"guidance_scale\": 3.0,\n  \"flow_shift\": 5.0,\n  \"seed\": 0,\n  \"negative_prompt\": \"nsfw, worst quality, bad anatomy, watermark, jpeg artifact\",\n  \"response_format\": \"b64_json\",\n  \"extra_params\": {\n    \"uncond_skip_layers\": [22],\n    \"slg_start\": 0.01,\n    \"slg_stop\": 1.0\n  }\n}\nJSON\n\ncurl --fail-with-body -sS http://localhost:8000/v1/images/generations \\\n  -H 'Content-Type: application/json' \\\n  --data-binary @request.json -o response.json && \\\npython3 - <<'PY'\nimport base64\nimport json\nfrom pathlib import Path\nresponse = json.loads(Path(\"response.json\").read_text())\nPath(\"moss-image.png\").write_bytes(base64.b64decode(response[\"data\"][0][\"b64_json\"]))\nprint(\"Saved moss-image.png\")\nPY\n```\n\nThe request uses the server's loaded model, so it also works with SFT.\nTo disable negative-branch skipping, set `uncond_skip_layers` to `[]`.\n\n### Layout prompts\n\nFor precise text and object placement, use the guide's experimental Layout format:\n`summary` describes the scene, and `items` supplies captions, visible `text`, and\nbounding boxes. Coordinates use `[y_min, x_min, y_max, x_max]` with the canvas\ncenter as origin; a 1024 × 1024 canvas spans −512 to +512 on each axis.\n\nEncode the layout as the API's `prompt` **string** and use the matching canvas size:\n\n```bash\npython3 - <<'PY'\nimport json\nfrom pathlib import Path\nlayout = {\n    \"summary\": {\"caption\": \"A travel poster on ivory paper with teal mountains and a Chinese heading.\"},\n    \"items\": [\n        {\"label\": \"text\", \"caption\": \"Large teal heading at the top.\",\n         \"text\": \"向山而行\", \"bbox\": [-432, -368, -288, 368]},\n        {\"label\": \"object\", \"caption\": \"Layered mountain silhouettes below the heading.\",\n         \"bbox\": [-176, -336, 400, 336]}\n    ],\n    \"bbox_coord_space\": \"abs_centralized\",\n    \"bbox_format\": \"yxyx\"\n}\nrequest = json.loads(Path(\"request.json\").read_text(encoding=\"utf-8\"))\nrequest[\"prompt\"] = json.dumps(layout, ensure_ascii=False, separators=(\",\", \":\"))\nrequest[\"size\"] = \"1024x1024\"\nPath(\"request-layout.json\").write_text(json.dumps(request, ensure_ascii=False), encoding=\"utf-8\")\nPY\n\ncurl --fail-with-body -sS http://localhost:8000/v1/images/generations \\\n  -H 'Content-Type: application/json' \\\n  --data-binary @request-layout.json -o response.json\n```\n\nDecode `response.json` with the image-saving snippet above.\n\n## Improve prompts with the official skill\n\nThe official [MOSS-Image Prompt Enhancer](https://github.com/OpenMOSS/MOSS-Image/tree/main/skills/moss-image-prompt-enhancer)\nturns an image idea into a detailed caption or a spatial Layout prompt.\nChoose a caption for scenes and illustrations, or Layout for posters, panels,\nand precise text placement. The skill prepares prompts; vLLM-Omni generates the image.\n\nCopy the complete `skills/moss-image-prompt-enhancer` directory, including its\n`scripts` and `references`, into your agent's skills directory. See the official\n[SKILL.md](https://github.com/OpenMOSS/MOSS-Image/blob/main/skills/moss-image-prompt-enhancer/SKILL.md)\nfor its workflow. For example, ask the agent:\n\n```text\nUse $moss-image-prompt-enhancer to create a 1024×1024 Layout prompt for\na travel poster with teal mountains on ivory paper. Put the exact Chinese\nheading “向山而行” at the top. Save the draft as draft.json and compile it\nto prompt.txt.\n```\n\nThe bundled `compile_prompt.py` converts top-left pixel boxes in the draft\ninto MOSS-Image's centered layout coordinates. It also supports caption drafts\nand needs only Python's standard library. Send the compiled `prompt.txt` as a\nstring, keeping the requested dimensions the same as the draft:\n\n```bash\npython3 - <<'PY'\nimport json\nfrom pathlib import Path\nrequest = json.loads(Path(\"request.json\").read_text(encoding=\"utf-8\"))\nrequest[\"prompt\"] = Path(\"prompt.txt\").read_text(encoding=\"utf-8\").strip()\nrequest[\"size\"] = \"1024x1024\"\nPath(\"request-enhanced.json\").write_text(json.dumps(request, ensure_ascii=False), encoding=\"utf-8\")\nPY\n\ncurl --fail-with-body -sS http://localhost:8000/v1/images/generations \\\n  -H 'Content-Type: application/json' \\\n  --data-binary @request-enhanced.json -o response.json\n```\n\n## Troubleshooting\n\n- **Unexpected sampling behavior:** send `flow_shift: 5.0` explicitly to match\n  the checkpoint's scheduler configuration.\n- **CUDA driver mismatch:** select the CUDA 12.9 image or update the host driver\n  to the matching supported version.\n\n## References\n\n- [MOSS-Image-Base model card](https://huggingface.co/OpenMOSS-Team/MOSS-Image-Base)\n- [MOSS-Image-SFT model card](https://huggingface.co/OpenMOSS-Team/MOSS-Image-SFT)\n- [MOSS-Image project and user guide](https://github.com/OpenMOSS/MOSS-Image)\n- [Official Chinese user guide](https://github.com/OpenMOSS/MOSS-Image/blob/main/USERGUIDE_ZH.md)\n- [Official Prompt Enhancer skill](https://github.com/OpenMOSS/MOSS-Image/blob/main/skills/moss-image-prompt-enhancer/SKILL.md)\n- [vLLM-Omni implementation PR #8926](https://github.com/vllm-project/vllm-omni/pull/8926)\n- [vLLM-Omni Docker images](https://hub.docker.com/r/vllm/vllm-omni/tags?name=mosimage)\n",
  "source": {
    "source": "vllm-omni",
    "repo": "vllm-project/vllm-omni",
    "ref": "main",
    "sha": "cda4a1ef83b295ba332146a7709e6277725edc9f",
    "path": "recipes/models/OpenMOSS-Team/MOSS-Image-Base.yaml",
    "edit_url": "https://github.com/vllm-project/vllm-omni/edit/main/recipes/models/OpenMOSS-Team/MOSS-Image-Base.yaml",
    "overlays": []
  }
}