Skip to main content
🟢 MOSS-Image guide is live
Read the guide
MossImage

MOSS-Image Layout JSON Spec

The bounding-box prompt format MOSS-Image uses for layout control, explained field by field with a complete worked example.

MOSS-Image layout JSON is a prompt format where you describe an image as a list of items, each with a label, a caption, optional text and a bounding box in absolute pixel coordinates centered on the canvas. You paste the JSON into the prompt field instead of a sentence, and the model places each item inside its box. This page documents the format as described in the official user guide and the technical report.

The feature is labeled "Experimental" by OpenMOSS. Last verified: October 20, 2026.

What does a layout JSON prompt look like?

Here is the official travel-poster example for a 1024 × 1024 canvas. It has one text item and one object item.

{
  "summary": {
    "meta": ["poster"],
    "canvas": "single",
    "caption": "A minimalist travel poster with a cream background, a blue mountain illustration, and the title EXPLORE at the top."
  },
  "items": [
    {
      "label": "text",
      "caption": "Large dark-blue uppercase title centered at the top.",
      "text": "EXPLORE",
      "bbox": [-416, -384, -288, 384]
    },
    {
      "label": "object",
      "caption": "A flat blue mountain illustration in the lower center.",
      "bbox": [-192, -288, 384, 288]
    }
  ],
  "bbox_coord_space": "abs_centralized",
  "bbox_format": "yxyx"
}

What does each field mean?

The top level has four keys: summary, items, bbox_coord_space and bbox_format. The summary describes the whole image, items describe the parts, and the last two keys declare how to read every box.

FieldTypeMeaning
summary.metaarray of stringsTags for the image type, for example ["poster"]
summary.canvasstring"single" for one canvas
summary.captionstringA natural-language description of the whole image
items[].labelstringtext, character or object
items[].captionstringHow this item should look
items[].textstringThe exact string to render; only for text items
items[].bboxarray of 4 integersThe item's box, read according to the two format keys
bbox_coord_spacestring"abs_centralized": absolute pixels, origin at the canvas center
bbox_formatstring"yxyx": [y_min, x_min, y_max, x_max]

How do the coordinates work?

Coordinates are absolute pixels with the origin at the center of the canvas, x increasing to the right and y increasing downward. On a 1024 × 1024 canvas, both axes run from -512 to +512. To convert a box from a normal top-left origin, subtract half the width from every x value and half the height from every y value.

Top-left origin box (1024²)Centered boxMeaning
y 96 to 224, x 128 to 896[-416, -384, -288, 384]Title band near the top
y 320 to 896, x 224 to 800[-192, -288, 384, 288]Illustration in the lower center

Remember the yxyx order: the first value is y_min, not x_min. Keep the coordinates consistent with the width and height you set in the generator; the box values do not rescale automatically.

Why absolute coordinates instead of 0-1000 relative ones?

The technical report found that zero-centered absolute coordinates generalize better to resolutions the model never saw in training than relative coordinates normalized to a 0-1000 range. That is why MOSS-Image departs from the convention used by several other layout-aware models.

How do I use a layout JSON prompt?

Paste the JSON into the prompt field with the width and height set to match the canvas you used for the boxes. In the Python API, pass json.dumps(layout, ensure_ascii=False) as the prompt string. In ComfyUI, the core MOSS-Image Layout Prompt node takes boxes from the Create Bounding Boxes node and emits the JSON for you.

The user guide also says natural language and structured input can be combined, so a layout JSON prompt can sit alongside style instructions.

Can I edit a layout without an image-to-image step?

Yes. Because the layout lives in the prompt, you can change a text string, move a box or swap an item and regenerate. The paper calls this layout-guided zero-shot modification and uses it to replace text or rearrange elements without any image conditioning.

How much does layout JSON improve results?

In the paper's RealLayoutArena human study, JSON layout prompts scored an Elo of 1622.87, against 1509.21 for detailed natural-language prompts and 1081.70 for short prompts. On the 7Bench benchmark, MOSS-Image with layout prompts reaches 0.88 mIoU and 0.70 layout AUC, versus 0.44 and 0.20 for Ideogram 4.

A second example: a three-step infographic

This example uses a portrait canvas of 768 × 1024, so x runs from -384 to +384 and y from -512 to +512.

{
  "summary": {
    "meta": ["infographic"],
    "canvas": "single",
    "caption": "A clean vertical infographic on white with a title and three numbered steps, each with a small green icon on the left and short text on the right."
  },
  "items": [
    {
      "label": "text",
      "caption": "Bold dark-green title centered at the top.",
      "text": "How Compost Works",
      "bbox": [-448, -320, -352, 320]
    },
    {
      "label": "object",
      "caption": "Flat green icon of a kitchen scrap bowl.",
      "bbox": [-256, -320, -128, -192]
    },
    {
      "label": "text",
      "caption": "Step one label in dark sans-serif.",
      "text": "1. Collect scraps",
      "bbox": [-240, -160, -144, 320]
    },
    {
      "label": "object",
      "caption": "Flat green icon of layered leaves.",
      "bbox": [-64, -320, 64, -192]
    },
    {
      "label": "text",
      "caption": "Step two label in dark sans-serif.",
      "text": "2. Layer greens and browns",
      "bbox": [-48, -160, 48, 320]
    },
    {
      "label": "object",
      "caption": "Flat green icon of a garden fork.",
      "bbox": [128, -320, 256, -192]
    },
    {
      "label": "text",
      "caption": "Step three label in dark sans-serif.",
      "text": "3. Turn weekly",
      "bbox": [144, -160, 240, 320]
    }
  ],
  "bbox_coord_space": "abs_centralized",
  "bbox_format": "yxyx"
}

Tips from the user guide

  • Keep the coordinates consistent with the output dimensions, which must be positive multiples of 16.
  • Use the text field for the literal string and the caption for its style; do not put the words only in the caption.
  • English captions are recommended because most training data is English, but text strings can be Chinese.
  • Insert \n inside a text string to force a line break.
  • The repository ships a prompt-enhancer skill that converts a pixel-coordinate draft into compact JSON with integer centered coordinates; a fine-tuned open-source layout enhancer is announced but not yet released.

FAQ

What labels are allowed in items[].label?

text, character and object, according to the ComfyUI Wiki description of the core node.

Do I need the summary block?

The official examples always include it. The summary caption is where the model reads overall style and background, so leave it in.

What happens if a box falls outside the canvas?

The user guide does not say. Keep boxes inside the -W/2 to +W/2 and -H/2 to +H/2 range to stay within documented behavior.

Can I use layout JSON with other models?

Not directly. The format is specific to MOSS-Image. MossImage's upcoming Layout Mode will turn the same boxes into a detailed natural-language prompt for other engines and export the JSON for MOSS-Image.

Sources