MOSS-Image API 接入指南

OpenMOSS 通过自己的 MOSI 平台提供 MOSS-Image API。 一次同步 POST 请求返回一张 PNG，普通提示词和 JSON 布局使用同一个接口。本页总结了官方接口文档；本站的在线生成器正是基于这个 API 构建的，写代码前可以先在那里试遍所有参数。

快速开始

1. 登录 platform.mosi.cn，打开 API Keys 创建密钥。
2. 把密钥存为环境变量——不要写进前端代码或提交到代码仓库。
3. 发起请求：

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": "一张极简风咖啡馆海报，奶油色纸张。大标题写着“慢一点”。",
    "negative_prompt": "nsfw, worst quality, bad anatomy, watermark, jpeg artifact",
    "size": "1024x1024",
    "n": 1,
    "response_format": "url",
    "output_watermark": { "enabled": false }
  }'

响应中的 data[0].url 是图片地址，usage 中是实际尺寸。请及时下载 PNG。

模型

模型 ID	版本	说明
moss-image-sft-1.0	SFT	推荐用于生成
moss-image-base-1.0	Base	原始基础模型
moss-image-sft-1.0-2026-10-09	SFT 快照	固定版本以便复现
moss-image-base-1.0-2026-10-09	Base 快照	固定版本以便复现

请求参数

字段	类型	必填	说明
model	string	是	上表中的模型 ID
prompt	string	是	最多 4,000 字符；普通文本或序列化后的布局 JSON
negative_prompt	string	否	最多 4,000 字符
prompt_enhance	boolean	否	true 时先用内置增强改写提示词再生图，默认 false
size	string	否	宽x高，每边 256–2048 且为 16 的倍数，总像素 ≤ 2,097,152。默认 1024x1024
n	integer	否	仅支持 1
seed	integer	否	0 到 2⁵³−1，不传则随机
num_inference_steps	integer	否	1–100
guidance_scale	number	否	0–10，显式传 0 有效
response_format	string	否	仅支持 url
output_watermark	object	否	传 {"enabled": false} 关闭默认可见水印

布局请求

把布局 JSON 序列化为字符串放进 prompt，并让 size 与坐标所对应的画布一致。保持 prompt_enhance 关闭，确保边界框原样传给模型。

import json, os, requests

layout = {
    "summary": {"meta": ["poster"], "canvas": "single",
                "caption": "一张极简旅行海报，奶油色背景。"},
    "items": [
        {"label": "text", "caption": "顶部的深蓝色大标题。",
         "text": "去远方", "bbox": [-416, -384, -288, 384]},
        {"label": "object", "caption": "扁平风格的蓝色山峦插画。",
         "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"])

可以在我们的布局编辑器里可视化地画好布局再复制 JSON。坐标规则见布局教程。

JavaScript（服务端）

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: '雨夜街头，一块粉色霓虹招牌写着“深夜营业”。',
    size: '1344x768',
    n: 1,
    response_format: 'url',
  }),
});
const { data, usage } = await res.json();
console.log(data[0].url, usage.output_width, usage.output_height);

请在服务端调用 API。把密钥暴露在浏览器里，任何人都能消耗你的额度。

错误码

HTTP	error.code	处理方式
400	invalid_field_value	检查字段名、类型或取值范围；使用快照模型时不要另传 version。
403	forbidden	检查 API 密钥和 Authorization: Bearer 请求头。
403	safety_guardrail_blocked	被平台安全审核拦截，请修改提示词。
403	prompt_enhancement_refused	提示词增强拒绝了请求，改用 prompt_enhance: false 重试。
404	resource_not_found	结果资源不存在，请重新提交。
429	concurrency_limit_exceeded / rate_limit_exceeded	等待进行中的任务完成，并降低请求频率。
502	prompt_enhancement_incomplete / upstream_invalid_result	保留请求标识并联系 MOSI。

关于重试的规则

生成是同步的，可能需要一段时间。官方文档特别提醒：超时或断连时任务可能仍在执行，因此不要自动重试，否则可能重复扣费。如果已经拿到图片 URL 只是下载失败，请重试下载。客户端超时请设置得足够长（官方示例为 900 秒）。

其他选择

一些第三方推理平台也提供 MOSS-Image，通常按张计价，并附带 LoRA 接口等功能。选择前请对比它们的模型版本、分辨率档位和数据政策。如果不想自己维护任何基础设施，本站的在线生成器按张计费、无需订阅，详见价格。

参数与错误码已于 2026 年 10 月 26 日对照 MOSI API 文档核实。平台可能变更，请以官方文档为准。