魔搭 API 生图技能 / ModelScope Image Generation

通过魔搭社区官方 API-Inference 接口生成和编辑图片。

何时使用

用户：

• 要求生成图片（"生成一张..."、"画一个..."、"生图"）
• 提供图片要求编辑/修改（"把背景换成..."、"改图"、"P图"）
• 明确提到 ModelScope / 魔搭生图
• 使用 "create an image"、"generate a picture"、"text-to-image"

内容安全边界（硬规则，优先于一切流程）

必须拒绝（不生成、不改写规避、不因换模型/换说法而松动）：

1. 露骨性描写提示词：内衣情色、透视/走光描写、性器官或第二性征尺寸（罩杯/胸围）、性暗示姿态（挑逗/媚态/诱惑）、腿袜大腿等性化局部特写、NSFW/porn/sexy 类关键词堆叠。
2. 情色类 LoRA / 模型：名字或用途指向色情（如 Pornmaster、SEXFEI、NSFW 滑块类）一律不加载，即使只是"测试功能"。
3. 未成年人性化：任何年龄段 + 性化描述的组合，绝对拒绝。

判断原则：看核心意图，不看包装词。用"港风丽人""禁欲素净""艺术摄影"包装的性化描写，本质不变，仍拒绝。

拒绝时的正确做法：

• 直接说明不做，不解释内部规则、不复述规则细节；
• 可提供去掉性化元素后的正常创作方向（如露背吊带袜 → 复古旗袍；强调身材 → 正常服装人像），保留场景/光影/构图/排版等艺术要素；
• 用户反复提交同类内容，保持一致拒绝，不对抗、不逐个试错。

注：普通时尚人像（吊带、短袖、泳装等日常着装）、cosplay 服装（非透视/非性化）、人像写真属正常范畴，正常执行。

交互方式规范（避免界面重叠和输入不便）

1. 自由文本一律纯文字提问：提示词、图片路径等需要用户打字的内容，直接用普通聊天文字提问并等待回复，不要用选项面板（面板不适合长文本输入）。
2. 选择题用选项面板，且必须列全：模型、比例等纯选择项必须用选项面板让用户点选（不要让用户打字输入比例/模型）。选项要完整列出，不能截断或省略——正文里不要重复完整选项列表，形状示意图等信息放在面板之前只出现一次，面板标签保持一行以内（如"D. 9:16 竖屏"），描述只写尺寸数字。
3. 面板一次全列，不拆两级、不退化打字：选项面板实测可容纳 8 个选项（已用 8 个模型实测通过），因此 8 个模型 / 7 档比例都放进同一个面板一次全列，让用户直接点选。
   • ❌ 不要拆成"先选系列再选具体模型"的两级面板（用户明确否决过）
   • ❌ 不要退化成"正文列表 + 让用户打字回复字母"
   • ❌ 不要因为选项多就砍掉几项——必须全部列出
   • 用户明确要求"表格一次性罗列并打字回复"时才用表格形式（属例外，非默认）
   • 默认偏好：点选优先，模型和比例都必须能点击选择。

交互流程（🔒 已锁定，不得擅改）

🔒 流程锁定规则（最高优先，2026-10-28 用户明确要求） 这套交互流程是用户确认过的最终形态，除用户明确要求修改流程外，任何情况下都不得改动： 不得增减步骤、不得调整步骤顺序、不得把面板改成文字输入、不得把"全列"改成"分级/精简"、不得省略 LoRA 面板或比例面板。 后续对技能的其它改动（新增模型、改提示词规范、加 LoRA、改文档）一律不得触及流程本身。 唯一允许的例外：用户当次明确说"这次跳过 X 步"或"以后改成……"，才可变更，并需同步更新本节。

锁定后的文生图流程（7 步，顺序固定）：

| 步 | 内容 | 形式 | |---|---|---| | 1 | 确认任务类型（文生图 / 改图） | 选项面板 | | 2 | 选模型（8 个全列） | 选项面板，一次点选 | | 3 | 输入画面描述 | 纯文字提问 | | 3.5 | 按模型分支重写提示词 + 让用户确认 | 纯文字 | | 3.6 | 问是否加载 LoRA（不加载 / 预置 / 自定义）→ 若加载再问强度 | 选项面板（必弹） | | 4 | 选比例（7 档全列） | 选项面板，一次点选 | | 5 | 执行并展示结果 | — |

锁定后的改图流程（5 步）： 任务类型 → 索要图片 → 选模型（2 项面板）→ 输入编辑指令（纯文字）→ 重写指令 + 必传原图比例 --size → 执行

当用户表达生图或改图意图时，不要直接执行，按上面锁定的步骤走：

第 1 步：确认任务类型。问用户：

你想做什么？

1. 文生图（从文字描述生成图片）
2. 修改图片（对已有图片进行编辑）

第 2 步：让用户选择模型。

⚠️ 必须用选项面板一次全列 8 个模型，不让用户打字、不拆两级（面板实测可放 8 项）：

请选择生图模型（8 个全列）： A. Z-Image-Turbo —— 速度快，中文人像好（日常推荐） B. Qwen-Image-2.1-Turbo —— Qwen 系最快，约 40 秒 C. Qwen-Image-2.1 —— 质量最高，原生 2K，支持透明底 D. MOSS-Image-SFT —— 写实/排版强，排队 3~9 分钟 E. FLUX.1-Krea-dev —— 艺术/写实风格强 F. Z-Image —— 非加速版，质量更高、速度较慢 G. Qwen-Image —— 老版本，速度快 H. Krea-2-Turbo —— 写实质感佳，约 30 秒

选项标签格式：字母. 模型短名，描述里写「完整模型 ID — 特点/速度」。用户直接说了模型名则跳过面板直接采用。

8 个模型各自的特点见下方「模型能力对照」表，面板选项描述里带上关键差异（速度/质量）。

若选择 2. 修改图片，先向用户索要图片（本地路径或 URL），再弹出面板（只有 2 个，一级即可）：

请选择改图模型： A. Qwen-Image-2.1 —— 编辑质量最高，细节保留更好（推荐） B. Qwen-Image-2.1-Turbo —— 编辑速度更快

第 3 步【文生图】：输入文生图提示词（用户选完模型后立即弹出）。用纯文字提问，不要用选项面板：

请输入文生图提示词，描述你想生成的图片内容 🎨 （比如："一只橘色的猫戴着围巾，坐在秋日窗台上，水彩插画风格"）

💡 描述越具体效果越好，可以包含：主体、场景、艺术风格、光线氛围。写不好也没关系，告诉我想画什么，我来帮你润色。

然后正常等待用户在聊天中打字回复。

第 3.5 步【文生图】：提示词优化（拿到提示词后、选比例前执行）。所有生图模型都要优化提示词，但规范不同，按所选模型分支：

分支 A：选了 Tongyi-MAI/Z-Image-Turbo 或 Tongyi-MAI/Z-Image（Z-Image 系）

按「人像摄影提示词专家」规范做中文扩写：

扩写规则（严格遵守）：

1. 语言自适应：用户用中文 → 输出中文；用户用英文 → 输出英文。主体描述与原文语言一致。
2. 纯文本输出：禁止 Markdown 符号（星号/井号），禁止括号中英对照，输出无任何格式标记。
3. 关键词完整保留：用户说的核心词一个都不能丢、不能改。
4. 拒绝短句：扩写成 3–5 个细节丰富的长句；每个名词至少补 2 个描述物理性质的修饰词。
5. 五维填充：① 质感（皮肤/布料/材质）② 构图与视角（平视/仰拍/景深虚化）③ 细节（五官/微表情/服饰）④ 光影色彩（柔光/硬光/色调）⑤ 氛围。
6. 结尾追加质量标签：照片级真实感，超精细纹理，锐利对焦，8K分辨率（英文输入则用对应英文标签）。
7. 收敛措辞：涉及人物的提示词若含 sexy/seductive/裸露等词，用stylish/confident/优雅等得体等价表达，避免被审核拒。

分支 B：选了 Qwen/Qwen-Image-2.1 或 Qwen/Qwen-Image-2.1-Turbo

按 Qwen 官方 8 步框架做英文重写（详见 references/qwen_t2i_rules.md）。要点：

• 描述一律英文（画面内文字保留用户原文脚本，放英文双引号内）
• 观察者口吻：现在时第三人称陈述，不对模型下指令
• 禁质量堆砌词：不写 "8K"/"masterpiece"/"highly detailed" 等
• 一段约 20 句、400–500 词；比例单独进 --size，不写进描述
• 8 步：拆分需求 → 定画幅 → 开头句 → 清点空间/文字清单 → 走画框（位置短语）→ 设定文字 → 光线独立成句 → 收尾整帧

分支 C：选了 openmoss/MOSS-Image-SFT

按 OpenMOSS 官方 Prompt Enhancer 规范做 caption 增强（详见 references/moss_prompt_rules.md）。要点：

• 默认 caption 模式：把用户一句话扩成一段连贯英文描述性 prose（不用 layout，除非用户要精确文字排版/海报——那种情况优先转 Qwen）
• 保留用户全部意图：主体、数量、关系、媒介、风格、排除项、可见文字逐字保留
• 补全但不越界：补主体外观/场景/镜头/光照/材质/色调/氛围，不发明用户没提的事实
• 禁冗余质量词：不写 "8K/masterpiece/ultra-realistic"
• 极简需求保持极简，丰富需求才展开
• 画面内可见文字放引号精确引用，与描述语言区分

分支 D：选了 black-forest-labs/FLUX.1-Krea-dev / krea/Krea-2-Turbo / Qwen/Qwen-Image（无专属官方规范）

这三个模型没有官方提示词增强规范，按通用结构化英文描述处理：

• 英文为主（Krea/FLUX 对英文更敏感；Qwen-Image 老版中英均可，中文输入可保留中文）
• 结构：主体与动作 → 外观细节 → 环境/背景 → 镜头与视角 → 光线 → 色调与氛围
• 具体名词 + 材质词优于抽象形容词（"磨砂哑光陶瓷台面" 优于 "高级质感"）
• 禁质量堆砌词：不写 "8K/ultra-realistic/best quality"，不写 midjourney 参数堆（--ar、权重括号等）
• 画面内文字：用引号精确写出，并说明位置/字体风格
• 长度控制在 3–6 句，不必强行拉长

四条分支（A/B/C/D）扩写完成后，都先让用户看一眼确认（一句话带过即可），再进入第 3.6 步选 LoRA。

第 3.6 步【文生图】：选择是否加载 LoRA（提示词确认后、选比例前弹出）。⚠️ 这是必选步骤，每次文生图都要弹，不可跳过（即使用户大概率不加载，也要问一次让用户确认"不加载"）。仅文生图有这一步，改图不支持 LoRA。用选项面板问用户：

是否需要加载 LoRA 模型？（LoRA 必须与主模型底座匹配） A. 不加载 —— 直接用主模型生成 B. 加载预置 LoRA —— 从下面按底座匹配选一个 C. 自定义 LoRA ID —— 自己填模型 ID

若选 B，按主模型底座列出预置 LoRA（详见 references/lora_rules.md 预置清单，底座不匹配的不要列）：

• 主模型是 Z-Image-Turbo / Z-Image → 列 Z-Image 系 LoRA（如国风、山海经）
• 主模型是 Qwen-Image-2.1 / 2.1-Turbo → 列 Qwen-Image-2.1 系 LoRA（如国风、旗袍写真）
• 主模型是 Krea-2-Turbo → 列 Krea 系 LoRA（如人像写真 krea2-CcFQWZ-Portrait）
• 主模型是 MOSS-Image-SFT → 列 MOSS 系 LoRA（如胶片氛围人像 zhouyemoss）
• 其他主模型（FLUX / Qwen-Image 老版）暂无预置，让用户走 C 自定义

选 B 后同样弹出「LoRA 强度」选择面板（与选 C 一致，见下方强度步骤）。

若选 C（自定义），跳出一个魔搭 LoRA 模型库页面链接，让用户直观浏览/选择 LoRA 的模型 ID，也可直接填 ID。给出链接时务必提醒底座匹配：

📚 魔搭 LoRA 模型库（请挑选与所选主模型底座匹配的 LoRA）： https://modelscope.cn/aigc/models?modelType=LoRA

💡 也可以直接把你选中的 LoRA 模型 ID 发我（形如 作者名/模型名）。

⚠️ 请确认该 LoRA 的「基础模型 / Base Model」与你的主模型一致：

• 主模型 Z-Image-Turbo / Z-Image → 找 Z-Image 底座 LoRA
• 主模型 Qwen-Image-2.1 / 2.1-Turbo → 找 Qwen-Image-2.1 底座 LoRA
• 主模型 FLUX / MOSS / Qwen-Image → 找对应底座 LoRA

然后等待用户回复 LoRA 模型 ID（纯文字输入）。

拿到 LoRA ID 后，立即弹出「LoRA 强度」选择面板（与比例一样用选项面板，不要让用户打字）：

LoRA 强度设为多少？（值越大风格越强，过大易糊/崩脸，建议 0.6~1.0） A. 1.0（默认，最强） B. 0.8（强风格但保留较多模型原生气质，最常用） C. 0.6（中等，画面更自然、脸部更稳） D. 0.4（弱，只轻微带一点风格倾向）

需要更精确的值（如 0.75）时，用户可在面板的「其他」里自行填写；用户不回复则按默认 1.0。

拿到强度后继续第 4 步选比例。执行时：强度 = 1.0 → --lora <ID>；强度非 1.0 → --lora <ID> --lora-weight <值>。每次只加载单个 LoRA。

第 4 步【文生图】：选择图片比例（拿到提示词后立即弹出）。共 7 档比例，用选项面板一次全列（不让用户打字、不拆两级）：

请选择生成比例（7 档全列）： A. 1:1 正方形 —— 2048×2048，头像/图标/商品主图 B. 3:2 横版 —— 1920×1280，横幅/风景 C. 2:3 竖版 —— 1280×1920，最修长 D. 4:3 横版 —— 2048×1536，接近相机原生 E. 3:4 竖版 —— 1536×2048，人像/小红书 F. 16:9 宽银幕 —— 2048×1152，PPT/横幅 G. 9:16 竖屏 —— 1152×2048，手机壁纸

（像素按所选模型从「分辨率预设」表取；Qwen 系即上列值，Z-Image 系走 1024 档，FLUX/Krea/MOSS 按 16 倍数——面板描述里写该模型对应的精确像素。）

⚠️ 永远完整展示 7 档，不许精简：用户已在提示词里给过比例时，照样弹完整 7 档，只把他给的那档在描述里标注「推荐（你原定）」，不要跳过面板、也不要只列相关的几档。

用户给的是非官方档比例（4:5、2.35:1 等）时，把「你原定的精确档」作为面板里的额外选项（共 8 项，面板可容纳）一起列出，例如 4:5 精确 1600×2000（你原定）。

像素值必须按所选模型从下方「分辨率预设」表中取对应尺寸（不同模型的预设像素不同）。正文可附形状示意图（只出现一次，不作为面板选项），示例（以 Qwen 2.1 系为例）：

A. 1:1 正方形

┌─────────┐
│         │
│         │   2048 × 2048
│         │
└─────────┘

B. 3:2 横版

┌─────────────┐
│             │   1920 × 1280
│             │
└─────────────┘

C. 2:3 竖版

┌───────┐
│       │
│       │   1280 × 1920
│       │
│       │
└───────┘

D. 4:3 横版

┌───────────┐
│           │   2048 × 1536
│           │
└───────────┘

E. 3:4 竖版

┌───────┐
│       │
│       │   1536 × 2048
│       │
│       │
└───────┘

F. 16:9 宽银幕

┌───────────────┐
│               │
│               │   2048 × 1152
└───────────────┘

G. 9:16 竖屏

┌────┐
│    │
│    │
│    │   1152 × 2048
│    │
│    │
└────┘

选项面板只放一行式短标签（如"G. 9:16 竖屏"），描述只写像素尺寸，不要重复示意图。必须用选项面板让用户点选比例，不要让用户打字输入比例；面板把 7 档比例全部列出。

第 5 步【文生图】：执行生成。把用户选的比例按所选模型查「分辨率预设」表得到 --size 值：

python scripts/image_gen.py generate --prompt "<用户提示词>" --model <所选模型> --size <预设表中对应尺寸>

使用等待模式（不加 --no-wait），生成完成后把图片展示给用户。

⚠️ MOSS-Image-SFT 排队策略（实测排队 3~9 分钟波动，非固定值）：选 MOSS 时执行前先告知用户该模型排队较慢，然后：

1. 用后台模式执行（run_in_background: true）+ --timeout 900，前台只等 300~480 秒容易被超时打断，而后台模式实测 5 分 28 秒 / 5 分 50 秒两次均正常出图；
2. 期间不要重复提交同一个 prompt（会重复排队）；
3. 若真的超过 900 秒，把 task_id 记下用 status --task-id 轮询，并主动提议「换 Qwen/Krea 快速出图」。

其他模型排队 15 秒~2 分钟属正常，前台等待即可。

第 3 步【改图】：输入编辑指令（用户选完改图模型后立即弹出）。用纯文字提问，不要用选项面板：

请描述你想怎么改这张图 ✏️

💡 说清三件事效果最稳：改哪里、改成什么样、其余保持不变。 （比如："把背景换成海边，人物和衣服保持不变"）

⚠️ 判断是否需要红框标注法：如果编辑目标满足以下任一条件，改用下方「红框标注法」，不要纯文字描述：

• 图上存在多个相似物体，用户只想改其中一个（如"移除右边那座塔"而图上有几座塔）
• 用户用红框/箭头截图标注了要改的位置
• 文字定位过一次但结果误改了其他区域

然后等待用户打字回复。

第 3.5 步【改图】：编辑指令重写（拿到编辑指令后、执行前）。改图模型是 Qwen 系列（Qwen/Qwen-Image-2.1 或 2.1-Turbo）时，必须按官方编辑重写规范先优化指令（详见 references/qwen_edit_rules.md），核心：

• 属性解耦：只把用户点名的属性改到位、改强烈，其余全部锁定（"保持 X 完全一致"）
• 双语言决策：描述语言跟用户（中文→中文）；画面内要渲染的文字单独决策（优先用户指定 > 图中主导语言 > 指令语言）
• 多图标签：≥2 张图必须用 <image1>/<image2>… 引用，并写明每张角色（画布 vs 素材）；单图自然称呼
• 身份守恒：换脸/换装/风格迁移时，身份来自参考图就直接指向那张图，别用文字描述五官（会毁相似度）
• 尺寸规则：wh_ratio（用户指定比例）与 ratio_follow（继承某张原图）互斥；扩图/全景/多视图各有推演
• 写成指令：以操作开头，站在"只拿着输入图的人"的视角写

重写后一句话带过给用户确认，无异议即执行。改图模型若非 Qwen 系列（当前不会出现），直接用用户原文。

第 4 步【改图】：确认输出设置。改图必须传 --size 保持原图比例（不传会返回 1024x1024 方图）：

• 读取原图实际宽高（PNG 头或 PIL），直接用原尺寸作为 --size（须在 64–2048 内，超出则按比例折算）
• 多图合成：画布图的比例 = --size；用户指定了新比例则按「分辨率预设」表换算
• 特殊需求（用户想改输出比例/做透明底）按用户要求来

第 5 步【改图】：执行编辑：

# 单图
python scripts/image_gen.py edit --image <图片路径> --prompt "<编辑指令>" --model <所选模型> --size <原图宽x高>
# 多图（按 image1/image2 顺序传多个 --image）
python scripts/image_gen.py edit --image <图1> <图2> <图3> --prompt "<编辑指令>" --model <所选模型> --size <画布图宽x高>

使用等待模式（不加 --no-wait），完成后把结果图展示给用户。复杂修改建议多轮小步迭代（每次只改一处），比一次大改稳。

跳过询问的情况：如果用户在最初请求里已明确说了用哪个模型或给了明确的比例（如"画一张竖屏壁纸"），可跳过对应的选择步骤，只确认缺失的信息。

红框标注法（精确定位改图，必须掌握）

纯文字描述定位不可靠——实测中"移除右边的塔"会误删图上所有相似物体（v1/v2 均失败）。对图上某一处做删除/修改时，用红框标注法，实测一次成功：

1. 画框：用 PIL 在原图上画出目标区域的红色矩形框，保存为标注图：

   from PIL import Image, ImageDraw
   im = Image.open("原图.png").convert("RGB")
   ImageDraw.Draw(im).rectangle([x1, y1, x2, y2], outline=(255, 0, 0), width=8)
   im.save("标注图.png")
   

   框要准确套住目标（先看图确认位置，别凭空估算——框偏了会删错区域或删不到）。
2. 改图指令模板（用标注图作为 --image 输入）：

   移除红色矩形方框内的 <目标物>，把该区域替换为 <留白/云雾/与周围融合的背景>。输出图中不得残留任何红色方框线条。方框之外的所有内容严格保持不变。

3. 提交后检查：确认输出无残留红线、框外内容未被动过；不满意就调整框的位置重试。

前置条件（一次性配置）

1. 在魔搭获取 API Key：https://modelscope.cn/my/myaccesstoken 注意：账号需绑定阿里云账号，否则 API 返回认证错误。
2. 设置环境变量：

   # Windows PowerShell
   $env:MODELSCOPE_API_KEY="ms-xxxxx"
   # Linux/Mac
   export MODELSCOPE_API_KEY="ms-xxxxx"
   

   或将 key 写入 scripts/.env 文件（MODELSCOPE_API_KEY=ms-xxxxx）。

执行环境与易错点（踩过的坑，务必照做）

1. Python 解释器：优先用系统/托管的基础解释器绝对路径（如 C:/Users/<用户>/.workbuddy/binaries/python/versions/3.13.12/python.exe）。不要假定某个 venv 里有 python.exe——实测某些 venv 的 Scripts/ 下没有 python.exe，直接调用会报 No such file or directory。脚本纯标准库，任何 Python 3.9+ 都能跑。
2. 保存路径参数是 --save / -o，不是 --output。写错会直接报 unrecognized arguments。
3. 尺寸参数是 --size "宽x高"（如 1536x2048），不要用 --width/--height（API 会静默忽略）。
4. 改图参数是 --image（可多个），不是 --input；未指定 --model 时自动用 Qwen/Qwen-Image-2.1。
5. 模型 ID 必须完整带命名空间：openmoss/MOSS-Image-SFT（不是 MOSS-Image-SFT）、krea/Krea-2-Turbo、Tongyi-MAI/Z-Image-Turbo。写错报 Invalid model id / Model not exists。
6. Windows 路径：含空格或中文时用双引号包裹；跨盘符用正斜杠（C:/...）。

快速开始

# 文生图（默认 Tongyi-MAI/Z-Image-Turbo，快且免费额度大）
python scripts/image_gen.py generate --prompt "一只金色的猫坐在窗台上，阳光照进来"

# 指定保存路径和尺寸
python scripts/image_gen.py generate --prompt "赛博朋克城市夜景" --save ./city.png --size 1280x720

# 高质量模式（慢一点但效果更好）
python scripts/image_gen.py generate --prompt "水墨山水画" --model Tongyi-MAI/Z-Image

# 改图（本地文件或图片 URL 均可；--size 传原图尺寸保持比例，不传会返回 1024x1024 方图）
python scripts/image_gen.py edit --image ./poster.png --prompt "移除画面左侧的路灯，其余保持不变" --size 1152x2048

# 查询已提交任务的状态（配合 generate --no-wait 拿到的 task_id）
python scripts/image_gen.py status --task-id <task_id>

LoRA 加载示意

LoRA 是挂在特定底座（base model）上的微调权重，必须与主模型底座匹配（详见 references/lora_rules.md）。仅在文生图分支可用，每次只加载单个 LoRA。

① 单个 LoRA（默认权重 1.0）

python scripts/image_gen.py generate \
  --model "Tongyi-MAI/Z-Image-Turbo" \
  --lora "Adse0P/Z-Image_LoRA_guofeng" \
  --prompt "国风仙侠天宫，漂浮在云海之上的宫殿" \
  --size 864x1152

② 单个 LoRA + 指定权重（如 0.8，弱化 LoRA 影响）

python scripts/image_gen.py generate \
  --model "Qwen/Qwen-Image-2.1" \
  --lora "qaz963plm/Qwen-Image-2.1-Q-lora" \
  --lora-weight 0.8 \
  --prompt "..." \
  --size 1536x2048

底座匹配速查：

| 主模型 | 可配 LoRA 底座 | |--------|---------------| | Z-Image-Turbo / Z-Image | Z-Image / Z-Image-Turbo | | Qwen-Image-2.1 / 2.1-Turbo | Qwen-Image-2.1 | | FLUX.1-Krea-dev | FLUX.1-Krea / FLUX | | Krea-2-Turbo | Krea-2 / Krea | | MOSS-Image-SFT | MOSS-Image | | Qwen-Image | Qwen-Image（老版） |

⚠️ 跨底座加载会矩阵维度报错或效果极弱。不确定 LoRA 底座时，先查它的模型页「Base Model / 基础模型」字段。 ⚠️ loras 能否生效取决于魔搭 API 后端是否支持该 LoRA，报 500「模型不存在」属正常，换实测可用的（见 references/lora_rules.md）。

参数说明

| 参数 | 默认值 | 说明 | |------|--------|------| | --prompt | 必填 | 图片描述（中英文均可） | | --model | Tongyi-MAI/Z-Image-Turbo | 模型 ID，见下方模型列表 | | --save / -o | ./outputs/自动命名.png | 保存路径 | | --size | 1024x1024 | 图片尺寸，格式 宽x高 | | --seed | 随机 | 随机种子 | | --negative-prompt | 无 | 负向提示词 | | --steps | 模型默认 | 采样步数 | | --cfg-scale | 模型默认 | 提示词引导系数 | | --lora | 无 | 单个 LoRA 模型 ID（须与主模型底座匹配） | | --lora-weight | 1.0 | LoRA 权重（给非 1.0 时自动转 dict） | | --no-wait | 等待完成 | 只提交任务并打印 task_id，不等待 | | --timeout | 300 | 最长等待秒数 |

可用模型

| 模型 ID | 特点 | |---------|------| | Tongyi-MAI/Z-Image-Turbo | ⭐ 默认。快速生成，免费额度大 | | Qwen/Qwen-Image-2.1-Turbo | 千问 2.1 加速版（2026.10），8 步出图，速度快（注意 Qwen Research 非商业许可） | | Qwen/Qwen-Image-2.1 | 千问 2.1 标准版（2026.09），生成+编辑统一，原生 2K，支持透明 PNG，质量最高（Qwen Research 非商业许可） | | openmoss/MOSS-Image-SFT | OpenMOSS 生图，写实与文字排版能力好；排队 3~9 分钟波动，建议后台模式 + --timeout 900 | | black-forest-labs/FLUX.1-Krea-dev | 黑森林 FLUX.1 Krea 版，写实人像/艺术风格强 | | Tongyi-MAI/Z-Image | Z-Image 非加速版，质量更高、速度较慢 | | Qwen/Qwen-Image | Qwen 老版本（非 2.1），可用，速度较快 | | krea/Krea-2-Turbo | Krea 加速版，写实质感佳，约 30 秒出图，实测可用 |

⚠️ 实测不可用（提交即报 40212 / 出图失败）：black-forest-labs/FLUX.1-schnell、stabilityai/stable-diffusion-xl-base-1.0、black-forest-labs/FLUX.1-Kontext-dev（能提交但出图 FAILED）。不要把这些加给用户。

分辨率预设（依据官方模型文档，按 API 上限折算）

魔搭 API-Inference 限制：宽高必须在 64–2048 之间，超过会被拒（官方本地预设最大 2752，API 不可直接用）。以下为按官方比例折算到 2048 内的预设，全部实测可用。

Qwen/Qwen-Image-2.1 与 2.1-Turbo 专用（源自官方 aspect_ratios 预设）：

| 比例 | API 可用尺寸 | |------|-------------| | 1:1 | 2048 × 2048 | | 3:2 | 1920 × 1280 | | 2:3 | 1280 × 1920 | | 4:3 | 2048 × 1536 | | 3:4 | 1536 × 2048 | | 16:9 | 2048 × 1152 | | 9:16 | 1152 × 2048 |

Tongyi-MAI/Z-Image-Turbo 专用：

| 比例 | 尺寸 | |------|------| | 1:1 | 1024 × 1024 | | 3:2 | 1152 × 768 | | 2:3 | 768 × 1152 | | 4:3 | 1152 × 864 | | 3:4 | 864 × 1152 | | 16:9 | 1280 × 720 | | 9:16 | 720 × 1280 |

FLUX.1-Krea-dev / Krea-2-Turbo / MOSS-Image-SFT 专用（尺寸需为 16 的正倍数，按比例取 16 对齐值）：

| 比例 | 尺寸 | |------|------| | 1:1 | 1024 × 1024 | | 3:2 | 1152 × 768 | | 2:3 | 768 × 1152 | | 4:3 | 1152 × 864 | | 3:4 | 1024 × 1360 | | 16:9 | 1280 × 720 | | 9:16 | 720 × 1280 |

编辑（edit）默认尺寸：官方编辑示例使用 2048 × 2048；输入图片支持 RGBA（透明底），本地文件自动转 data URI，URL 直接透传。

edit（改图）命令可用模型（未指定 --model 时自动用 Qwen/Qwen-Image-2.1，即选项 A）：

| 模型 ID | 说明 | |---------|------| | Qwen/Qwen-Image-2.1 | ⭐ 选项 A，编辑质量最高，细节保留更好 | | Qwen/Qwen-Image-2.1-Turbo | 选项 B，编辑速度更快 |

工作原理

1. POST https://api-inference.modelscope.cn/v1/images/generations （Header X-ModelScope-Async-Mode: true），返回 task_id
2. 轮询 GET /v1/tasks/{task_id}（Header X-ModelScope-Task-Type: image_generation）
3. task_status 变为 SUCCEED 后，从 output_images 下载图片并保存

故障排查

| 问题 | 解决 | |------|------| | 401 认证错误 | 检查 API Key，确认账号已绑定阿里云 | | must be integer in [64,2048] | 尺寸超限，API 限制宽高 64–2048，改用上方预设表中的尺寸 | | 尺寸不生效 / 总是 760×1280 | 确认用 size: "宽x高" 字符串参数，width/height 数字参数会被 API 静默忽略 | | 内容审核失败 | 收敛措辞（光线/氛围/服装层面）；但露骨性描写属安全边界，直接拒绝不做改写，见「内容安全边界」 | | LoRA 加载报 500 apiInferModelDownload ... 模型不存在 | 该 LoRA 后端不支持加载（模型页有示例代码 ≠ 后端可用）。换 references/lora_rules.md 里「✅ 实测可用」的，或让用户换一个 | | 任务成功但稍后查报 task not found | 任务结果清理很快，查到 SUCCEED 必须立刻下载，建议用等待模式 | | 任务超时 | 加大 --timeout（默认 300 秒）；MOSS-Image-SFT 实测排队 3~9 分钟，改用后台模式 + --timeout 900（前台等待易被打断），仍超时则用 status --task-id 轮询，勿重复提交 | | submit failed with code: 40212 | 该模型 API-Inference 后端不可用（实测 FLUX.1-schnell、SDXL 均报此错），换「可用模型」表里的模型 | | Model not exists / Invalid model id | 模型 ID 拼写或命名空间不对（如 MOSS 应为 openmoss/MOSS-Image-SFT 而非 MOSS-Image-SFT） | | 服务端偶发 500（unknown FC status: Dequeued） | 后端偶发，直接重试一次通常成功 | | 改图变成整图重画 | 确认用 edit 命令且脚本为修复版（官方参数是 image_url 数组，image 字段会被 API 静默忽略）；改图时建议显式传 --size（不传默认返回 1024x1024） | | 无网络依赖报错 | 本技能纯标准库，无需 pip install |

出图效果建议

• 描述越具体越好："一只金色的猫" → "一只绿眼睛的蓬松金猫，坐在丝绒垫上"
• 指定风格："吉卜力风格的山景"、"水彩画风格"
• 补充光线和氛围："温暖的橙色夕阳，宁静的海面"