UniLLM 图片生成 MCP

用一套统一接口生成与编辑图片，屏蔽各家协议差异。本 Skill 背后是一个 MCP Server。

支持 8 家厂商：字节豆包 Seedream（火山方舟）、阿里通义万相（DashScope）、智谱 CogView、硅基流动 SiliconFlow、MiniMax，以及海外 OpenAI 与 Stability AI，另有任意自定义 OpenAI 兼容端点。

> <skill-directory> 指本 Skill 所在目录，而非用户项目目录。
> MCP Server 源码位于 <skill-directory>/server/。

🖼️ 核心：尺寸与宽高比

图片生成的第一道门槛是尺寸。 不同厂商支持的尺寸集不同：豆包用 1024x1024，通义万相用 1024*1024（星号分隔），Stability 用 aspect_ratio 而非像素。本 MCP 把这些差异全部归一化到你这边 —— 你只需按统一习惯传参，MCP 负责翻译成上游能懂的形式。

三层尺寸要素

> 关键理解：size 同时决定清晰度与画幅。1024x1024 是方形，1280x720 是 16:9 横屏，720x1280 是 9:16 竖屏。

宽高比速查

> 用 size 传任意厂商支持的像素即可；不在支持列表内的尺寸会被规范化到最接近的合法值并明确提示。

参数规范化：不会静默改

⏱️ 核心：两条调用链路

图片生成有两种后端形态，本 MCP 自动识别：

同步直出（豆包 / 智谱 / SiliconFlow / MiniMax / OpenAI / Stability）

image_generate(...)   # 一次调用，直接拿到图片文件

异步任务（通义万相）

image_generate(...)   # 内部自动「建任务 → 轮询 → 下载」，你无感

> 与视频不同，图片生成很快（数秒到数十秒），因此本 MCP 统一封装成阻塞式，默认最长等 3 分钟（可调）。你不需要手动轮询。

工具一览

> 工具在 Agent 中的实际名称形如 mcp__plugin_unillm-image_unillm-image__image_generate，调用时用短名即可。

厂商能力矩阵

接口形态说明：本 MCP 内置 4 种适配器 ——
openai-images（/images/generations + /images/edits）、
dashscope-async（建任务 + 轮询 /tasks/{id}）、
minimax-images（/image_generation，注意 base_resp.status_code）、
stability-image（/v2beta/stable-image/generate/{engine}，multipart）。

When to Use

• 需要文生图：给一句 prompt，产出图片文件。
• 需要图生图 / 改图：给参考图 + 指令，产出新图。
• 需要批量出图：一次生成多张，挑选最佳。
• 需要在多家厂商间切换或对比：同一套参数，换 provider 即可。
• 上游是视频生成本 Skill 的图生视频：先生成首帧图片，再交给视频 MCP。

When NOT to Use

• 需要视频：请用视频生成 MCP（unillm-video）。
• 需要 LLM 对话 / 视觉理解：请用多模态 MCP（unillm-multimodal）或文本 MCP（unillm-text）。
• 需要修图但无参考图能力：部分厂商（智谱、MiniMax）不支持编辑，请换支持 editModels 的厂商。

参数说明

image_generate

image_edit

密钥配置

各厂商密钥通过环境变量注入，本 MCP 不硬编码、不落盘、不回显：

> 用 image_provider_status() 可查看哪些厂商已配好密钥 —— 返回的是掩码（如 sk-***abcd），不会泄露明文。

调用示例

1. 方形主图（最常用）

image_generate(prompt="极简风咖啡杯产品图，白底，柔光", size="1024x1024")

2. 横版 Banner

image_generate(prompt="科技感数据可视化背景，深蓝渐变", size="1280x720")

3. 竖版海报（小红书 / 抖音）

image_generate(prompt="夏季新品奶茶海报，清新配色", size="720x1280")

4. 批量出图挑最佳

image_generate(prompt="国风水墨山水，留白", count=4)

5. 换厂商对比效果

image_generate(prompt="赛博朋克城市夜景", provider="siliconflow", model="black-forest-labs/FLUX.1-schnell")
image_generate(prompt="赛博朋克城市夜景", provider="zhipu")   # 智谱 cogview-3-flash 免费

6. 图生图（改图）

image_edit(prompt="把白天改成黄昏，加暖色光晕", image="./unillm-images/doubao-t2i-xxx.png", provider="doubao")

7. 固定种子复现

image_generate(prompt="宇航员在月球上", seed=42)

8. 检查可用厂商

image_provider_status()   # 看哪些密钥已配置
image_list_providers()    # 看完整能力矩阵

选型建议

错误处理

注意事项

• 图片落盘：生成结果默认保存到 ./unillm-images/，返回文件路径（可选内联 base64，用 UNILLM_IMAGE_INCLUDE_BASE64=true 开启）。
• 通义万相是异步的：内部自动轮询，你无感，但耗时会比其他厂商长几秒。
• 智谱 cogview-3-flash 免费：适合压测与快速验证。
• 国内直连：豆包 / 通义 / 智谱 / SiliconFlow / MiniMax 均可直连；OpenAI 与 Stability 通常需代理，或把 baseUrl 指向中转网关。
• 海外厂商默认不配置：需显式设置对应环境变量才会出现在可用列表。

可配置项

安装与自检

cd <skill-directory>/server
npm install          # 安装依赖
npm run build        # 编译 TypeScript
node test-e2e.mjs    # 端到端契约自检（46 项断言）

自检会启动一个本地假图片服务，让 Server 真实走完
「HTTP 请求 → 拿到图片 → 落盘 → 返回路径」全链路，
并覆盖 4 种接口形态、异步轮询、multipart 编辑、契约拒绝、参数规范化等场景。