MOSS-Image API guide

OpenMOSS serves MOSS-Image through its own API on the MOSI platform. One synchronous POST returns one PNG. The same endpoint handles plain prompts and JSON layouts. This page summarizes the official reference; the online generator on this site is built on exactly this API, so you can try every parameter before writing code.

Quick start

1. Sign in at platform.mosi.cn, open API Keys and create a key.
2. Store it as an environment variable — never in client-side code or a repository.
3. Send a request:

export MOSS_API_KEY="your-key"

curl --max-time 900 -X POST "https://api.mosi.cn/v1/images/generations" \
  -H "Authorization: Bearer $MOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moss-image-sft-1.0",
    "prompt": "A minimalist café poster on cream paper. The large title reads \"SLOW COFFEE\".",
    "negative_prompt": "nsfw, worst quality, bad anatomy, watermark, jpeg artifact",
    "size": "1024x1024",
    "n": 1,
    "response_format": "url",
    "output_watermark": { "enabled": false }
  }'

The response contains the image URL in data[0].url and the actual size in usage. Download the PNG promptly.

Models

Model ID	Checkpoint	Notes
moss-image-sft-1.0	SFT	Recommended for generation
moss-image-base-1.0	Base	Raw base model
moss-image-sft-1.0-2026-10-09	SFT snapshot	Pin for reproducibility
moss-image-base-1.0-2026-10-09	Base snapshot	Pin for reproducibility

Request parameters

Field	Type	Required	Notes
model	string	Yes	One of the model IDs above
prompt	string	Yes	Up to 4,000 characters; plain text or serialized layout JSON
negative_prompt	string	No	Up to 4,000 characters
prompt_enhance	boolean	No	true rewrites the prompt with the built-in enhancer before generating. Default false
size	string	No	WIDTHxHEIGHT, each 256–2048 and a multiple of 16, total ≤ 2,097,152 px. Default 1024x1024
n	integer	No	Only 1 is supported
seed	integer	No	0 to 2⁵³−1; random when omitted
num_inference_steps	integer	No	1–100
guidance_scale	number	No	0–10; 0 is valid
response_format	string	No	Only url
output_watermark	object	No	{"enabled": false} disables the default visible watermark

Layout requests

Send the layout JSON as a string in prompt, and keep size equal to the canvas the coordinates were written for. Leave prompt_enhance off so the boxes reach the model unchanged.

import json, os, requests

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

resp = requests.post(
    "https://api.mosi.cn/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['MOSS_API_KEY']}"},
    json={
        "model": "moss-image-sft-1.0",
        "prompt": json.dumps(layout, ensure_ascii=False),
        "size": "1024x1024",
        "n": 1,
        "response_format": "url",
    },
    timeout=900,
)
resp.raise_for_status()
print(resp.json()["data"][0]["url"])

Build layouts visually in our layout editor and copy the JSON. Coordinates are explained in the layout guide.

JavaScript (server-side)

const res = await fetch('https://api.mosi.cn/v1/images/generations', {
  method: 'POST',
  signal: AbortSignal.timeout(900_000),
  headers: {
    Authorization: `Bearer ${process.env.MOSS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'moss-image-sft-1.0',
    prompt: 'A neon sign that reads "OPEN LATE" on a rainy street at night.',
    size: '1344x768',
    n: 1,
    response_format: 'url',
  }),
});
const { data, usage } = await res.json();
console.log(data[0].url, usage.output_width, usage.output_height);

Call the API from your server. Exposing the key in a browser lets anyone spend your credits.

Errors

HTTP	error.code	What to do
400	invalid_field_value	Fix the field name, type or range. Don’t pass a version with a snapshot model.
403	forbidden	Check the API key and the Authorization: Bearer header.
403	safety_guardrail_blocked	The platform’s safety review blocked the request. Change the prompt.
403	prompt_enhancement_refused	The enhancer refused. Retry with prompt_enhance: false.
404	resource_not_found	The result asset is gone. Submit a new request.
429	concurrency_limit_exceeded / rate_limit_exceeded	Wait for running jobs, then slow down.
502	prompt_enhancement_incomplete / upstream_invalid_result	Keep the request ID and contact MOSI.

The retry rule

Generation is synchronous and can take a while. The official docs warn that a timed-out or disconnected request may still be running, so do not retry automatically — you could pay twice. If you already have an image URL and only the download failed, retry the download instead. Use a long client timeout (the examples use 900 seconds).

Alternatives

Third-party inference providers also host MOSS-Image, often with per-image prices and extras such as LoRA endpoints. Compare their model version, resolution tiers and data policies with the official API before choosing. If you would rather not run any infrastructure, our online generator charges per image with no subscription; see pricing.

Parameters and error codes checked against the MOSI API reference on 26 October 2026. The platform may change; the official docs are authoritative.