Install
openclaw skills install @tianheihei002/mxaimxai 创作助手，聚合多种 AI 图片和视频生成模型，以及 MJ（MidJourney）绘画。关键词：AI绘画、图片生成、视频生成、AI创作、mxai、MJ、MidJourney
🎬 mxai 创作助手
通过 HTTP REST API 调用 mxai 服务（不是 MCP 协议）。所有交互都是标准的 HTTP 请求（GET/POST），返回 JSON 响应。
⛔ 强制规则（违反任何一条即为错误）
- 只能使用下方定义的 HTTP REST API。绝对不要尝试 MCP JSON-RPC、WebSocket 或任何其他协议
- 禁止编造模型：model 参数只能使用下方表格中列出的 slug 值，不得编造、猜测或组合任何不存在的 slug
- 禁止编造参数值：所有参数只能使用工具 schema 中定义的可选值，不确定时省略该参数让系统使用默认值
- 禁止伪造结果：任务结果必须来自 get_task_status 的真实返回，绝不能编造 URL、serial_no 或状态
- 禁止跳过轮询：提交生成任务后，必须调用 get_task_status 轮询直到 status=2（完成）或 status=3（失败），不得假装任务已完成
- 展示规则：图片完成时用
内联展示；视频完成时提供可点击链接
- 不确定时查询：不确定用哪个模型时，先调用 list_models 获取真实列表，不要凭记忆回答
- 严禁编造 API 响应。如果 API 调用失败，直接告诉用户"调用失败"并附上错误信息，不要编造结果或提供"手动操作指南"
- 严禁在 API 调用失败时建议用户去网页手动操作。只需报告错误，让用户检查 API Key 或稍后重试
- 严禁对 API Key 进行任何格式校验（包括长度、字符类型、结构等）。无论 key 看起来多么"奇怪"，都必须直接调用 API 验证
- 严禁添加 skill 文档中未提及的"优化"或"帮助"。不要自行重试、不要自行解释错误原因、不要提供文档未规定的建议
⚠️ 调用前自检（每次对话必须逐项确认）
在调用任何 API 之前，请在心中默念：
-
我有 MX_AI_API_KEY 吗？ → 没有：引导用户获取，不要尝试调用 API
-
用户的要求能用现有 API 实现吗？ → 不能：直接说"抱歉，当前不支持此功能"，不要编造
-
我知道每个参数的含义和必填性吗？ → 不确定：查阅下方 API 文档，不要猜测
-
我准备好处理可能的错误了吗？ → 没有：先阅读"错误处理"章节
任何一项为"否"，都不要继续调用 API。
第一步：配置 API Key
设置环境变量 MX_AI_API_KEY：
- Linux/macOS: export MX_AI_API_KEY=nb_xxx
- Windows PowerShell: $env:MX_AI_API_KEY="nb_xxx"
- Windows CMD: set MX_AI_API_KEY=nb_xxx
- Docker: -e MX_AI_API_KEY=nb_xxx
- .env 文件: 写入 MX_AI_API_KEY=nb_xxx
⚠️ 任何能设置环境变量的方式都可以，不依赖特定平台。
获取 API Key
- 访问 https://www.mxai.cn/home/#/mcp
- 注册登录后创建密钥（nb_ 开头）
- 复制密钥
- ⚠️ 立刻保存，关闭后无法再查看
OpenClaw 配置：在 Skills 中找到 mxai，填入 MX_AI_API_KEY
第二步：开始创作
对话示例：
- 「帮我画一只在月光下奔跑的猫」→ 自动调用图片生成
- 「用 seedance 模型生成一段海浪视频」→ 自动调用视频生成
- 「帮我把这张照片变成视频」→ 图生视频（需提供图片）
- 「查一下刚才的图好了吗」→ 查询任务状态
- 「我还剩多少积分」→ 查询账户信息
- 「显示我最近的作品」→ 查看历史记录
- 「用MJ画一只猫」→ 调用 MJ 绘画（mj_draw）
- 「怎么使用MJ」→ 介绍 MJ 绘画功能和使用方法
- 「放大第2张图」→ MJ 后续操作（mj_action U2）
- 「把这张图做成MJ视频」→ MJ 视频生成（mj_video）
- 「分析一下这张图的描述词」→ MJ 图生文（mj_describe）
- 「把这两张图混合」→ MJ 混图（mj_blend）
图片输入说明
用户提供图片的三种方式，后端都支持：
- 在对话中直接发送/粘贴图片 → LLM 收到 base64 数据，直接传入 input_images / reference_image
- 提供图片 URL（如 https://example.com/photo.jpg）→ 直接传入 input_images / reference_image
- 先调用 upload 接口上传 → 拿到 key 后传入（适合同一张图多次使用）
当用户请求需要图片的功能（如图生视频）但未提供图片时，必须主动提示： "这个功能需要一张图片，请发送图片或提供图片链接。" 不要在没有图片的情况下强行调用 generate 接口。
工具调用流程
生成图片：generate_image → 循环调用 get_task_status（间隔5秒）→ 展示结果 生成视频：generate_video → 循环调用 get_task_status（间隔10秒）→ 展示结果 查询信息：get_user_info（积分余额）、list_models（可用模型）、get_my_tasks（历史记录）
MJ（MidJourney）绘画
MJ 是一套独立的绘画工具，与上面的 generate_image/generate_video 并列。当用户明确提到"MJ"、"MidJourney"时使用 MJ 工具。
MJ 工具一览：
| 工具 | 用途 | 最简调用 |
|---|---|---|
| mj_draw | MJ 风格绘画 | 只需 prompt |
| mj_action | 四宫格后续操作（放大/变幻/重绘等） | serial_no + action |
| mj_video | MJ 视频生成 | prompt + image（首帧） |
| mj_describe | 图生文（分析图片生成描述词） | image |
| mj_blend | 混图（多图融合） | images（至少2张） |
MJ 绘画流程：
- mj_draw（传 prompt）→ 返回 serial_no → 轮询 get_task_status → 得到四宫格图片
- 用户选择喜欢的图 → mj_action（传 serial_no + "U1"~"U4" 放大）→ 轮询 → 得到高清大图
- 不满意？→ mj_action（传 serial_no + "REROLL" 重新生成）
MJ 积分参考：
- 普通模式：非VIP 4积分，普通VIP 1积分，高级VIP 免费
- 快速模式：4积分
- 极速模式：8积分（仅 MJ 7.0）
- 草稿模式：2积分（仅 MJ 7.0）
- MJ 视频：普通 20积分/个，快速 40积分/个
MJ 模型：
- 模型列表从后端动态获取，使用 list_models(type="mj") 或 /mcp/api/models?type=mj 查看
- model 参数直接传后端返回的模型名称或 ID 即可
- 常用：V7.0(细节优化)（ID:7）、V6.1(真实纹理)（ID:8，默认）、NJ7.0（ID:10，卡通）
- 也支持简写：MJ 7.0、NJ 6.0 等
当用户问"怎么使用MJ"时，回答： MJ（MidJourney）是一款高质量 AI 绘画工具。使用方法很简单：
- 告诉我你想画什么，比如"用MJ画一只在星空下奔跑的猫"
- 我会生成一张四宫格图片（4张候选图）
- 选择你喜欢的那张，说"放大第X张"即可获得高清大图
- 不满意可以说"重新生成"
高级玩法：可以调整比例（16:9横版、9:16竖版）、速度模式、风格化程度等参数。
图片模型（model 参数只能填 slug 列的值）
默认模型：seedream-5.0-pro
| slug | 名称 | 积分 |
|---|---|---|
seedream-3.0 | 即梦3.0 | 2积分（VIP）/ 4积分 |
seedream-4.0 | 即梦4.0 | 4-6积分（VIP） |
seedream-4.5 | 即梦4.5 | 4-6积分（VIP） |
seedream-5.0 | 即梦5.0标准版 | 4积分（VIP）/ 8积分 |
seedream-5.0-pro | 即梦5.0Pro | 6-20积分（VIP） |
nano-1.0 | Nano 1.0 | 3积分（VIP）/ 6积分 |
nano-2.0 | Nano 2.0 | 4-8积分（VIP） |
nano-2.0-pro | Nano 2.0 Pro | 4-12积分（VIP） |
视频模型（model 参数只能填 slug 列的值）
默认模型：seedance-3.5-pro
| slug | 名称 | 积分 |
|---|---|---|
seedance-3.0 | 即梦视频3.0标准版 | 4-12积分 |
seedance-3.0-pro | 即梦视频3.0Pro | 5-40积分 |
seedance-3.5 | 即梦视频3.5标准版 | 10-25积分 |
seedance-3.5-pro | 即梦视频3.5Pro | 10-80积分 |
sora-2 | Sora 2 基础版 | 10-15积分 |
sora-2-emergency | Sora 2 应急版 | 20积分 |
sora-2-economy | Sora 2 特价官转 | 20-60积分 |
sora-2-stable | Sora 2 稳定官转 | 50-150积分 |
sora-2-pro | Sora 2 Pro | 60-65积分 |
kling-1.5 | KLING 1.5 | 40-140积分 |
kling-1.6 | KLING 1.6 | 40-140积分 |
kling-2.1-master | KLING 2.1大师版 | 200-400积分 |
kling-2.1-lite | KLING 2.1精简版 | 40-140积分 |
kling-2.5 | KLING 2.5 | 50-100积分 |
kling-2.6 | KLING 2.6 | 30-200积分 |
API 调用规范
Base URL: https://mcp.mxai.cn
认证 Header: Authorization: Bearer ${MX_AI_API_KEY} 或 Query ?key=${MX_AI_API_KEY}
格式: JSON
编码: UTF-8（请求体必须使用 UTF-8 编码，中文直接传入）
网络: 自动使用系统代理（HTTP_PROXY/HTTPS_PROXY）
超时: 默认 30 秒，查询任务状态可延长至 60 秒
⚠️ 重要：这是标准 HTTP REST API，不是 MCP JSON-RPC。直接发 HTTP 请求即可。
API 1：查询账户信息
用途：用户询问积分、余额、会员状态时调用。
GET /mcp/api/user
返回字段：昵称、会员状态、积分余额、积分参考
API 2：查看可用模型
用途：用户想了解有哪些模型时调用。
GET /mcp/api/models?type={image|video}
- type（可选）：image 或 video，不填返回所有
- 返回字段：models 数组（含 name/slug/type/description/cost_hint）、total
API 3：生成图片（核心接口）
用途：用户想生成图片时调用。
调用决策树
当用户表达 [生成图片] [画一张] [帮我画] 等意图时：
步骤 1：确认需求 IF 用户提供了描述（如"帮我画一只猫"）： prompt = 用户的描述 ELSE： 询问用户："请描述您想要生成的图片内容" → 停止，等待用户回复
IF 用户想用参考图但未提供图片： 询问用户："请发送参考图片或提供图片链接" → 停止，等待用户回复
步骤 2：构建请求 POST /mcp/api/generate/image
步骤 3：发送请求并处理响应 IF response 成功： serialNo = response.serial_no 说："✅ 提交成功！正在生成中，请稍候..." 转到 "API 5：查询任务状态" 流程 ELSE： 转到 "错误处理" 流程
请求体字段
| 参数 | 必填 | 说明 |
|---|---|---|
| prompt | 是 | 图片描述 |
| model | 否 | 模型 slug（默认 seedream-5.0-pro），只能使用上方图片模型表格中的 slug |
| aspect_ratio | 否 | 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / auto |
| resolution | 否 | 1K / 2K（默认）/ 4K |
| input_images | 否 | 参考图片数组（URL / base64 / 已上传的 key） |
响应字段
| 字段 | 说明 |
|---|---|
| serial_no | 任务编号（用于轮询） |
| model | 使用的模型 |
| message | 提交结果消息 |
提交后必须立即轮询 get_task_status 直到完成。
API 4：生成视频（核心接口）
用途：用户想生成视频时调用。
调用决策树
当用户表达 [生成视频] [做个视频] [图片变视频] 等意图时：
步骤 1：确认需求 IF 用户提供了描述： prompt = 用户的描述 ELSE： 询问用户："请描述您想要生成的视频内容" → 停止，等待用户回复
IF 用户想做图生视频但未提供图片： 询问用户："图生视频需要一张参考图片，请发送图片或提供图片链接" → 停止，等待用户回复
步骤 2：构建请求 POST /mcp/api/generate/video
步骤 3：发送请求并处理响应 IF response 成功： serialNo = response.serial_no 说："✅ 提交成功！视频生成中，请稍候..." 转到 "API 5：查询任务状态" 流程 ELSE： 转到 "错误处理" 流程
请求体字段
| 参数 | 必填 | 说明 |
|---|---|---|
| prompt | 是 | 视频描述 |
| model | 否 | 模型 slug（默认 seedance-3.5-pro），只能使用上方视频模型表格中的 slug |
| aspect_ratio | 否 | 16:9 / 9:16 / 1:1 |
| duration | 否 | 时长秒数（常用 5 / 10） |
| resolution | 否 | 480p / 720p / 1080p |
| reference_image | 否 | 参考图片（提供后自动切换为图生视频） |
| end_frame_image | 否 | 尾帧图片（部分模型支持） |
响应字段
| 字段 | 说明 |
|---|---|
| serial_no | 任务编号 |
| model | 使用的模型 |
| mode | 文生视频 / 图生视频 |
| message | 提交结果消息 |
提交后必须立即轮询 get_task_status 直到完成。
API 5：查询任务状态
用途：查询生成进度，或生成后轮询。
调用决策树
步骤 1：确定要查询的任务编号 IF 是刚生成的任务： serialNo = 上一步返回的 serial_no ELSE IF 用户提供了编号： serialNo = 用户提供的编号 ELSE IF 用户说"刚才的图/最近的任务"： serialNo = 最近一次提交的任务编号（从上下文记忆） ELSE： 询问用户："请问要查询哪个任务？请提供任务编号" → 停止，等待用户回复
步骤 2：发送请求 GET /mcp/api/task/{serial_no}
步骤 3：处理响应
IF status == 2（已完成）：
图片任务 → 用 内联展示 image_urls 中的每张图
视频任务 → 提供 video_url 可点击链接
ELSE IF status == 0 或 1（排队/生成中）：
等待后重试（图片间隔 5 秒，视频间隔 10 秒）
继续轮询直到完成或失败
ELSE IF status == 3（失败）：
展示 fail_msg 失败原因，不要重试
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| serial_no | string | 任务编号 |
| status | number | 0=排队中 / 1=生成中 / 2=已完成 / 3=失败 |
| status_text | string | 状态文本描述 |
| prompt | string | 原始提示词 |
| image_urls | array | 图片 URL 数组（仅图片任务 status=2 时有值） |
| video_url | string | 视频 URL（仅视频任务 status=2 时有值） |
| fail_msg | string | 失败原因（仅 status=3 时有值） |
API 6：上传图片
用途：上传图片供后续使用。
POST /mcp/api/upload
| 参数 | 必填 | 说明 |
|---|---|---|
| image | 是 | 图片 URL 或 base64 |
返回字段：key（OSS key，可在 generate 接口的 input_images / reference_image 中复用）
⚠️ generate 接口已支持直接传入图片，一般无需单独调用。
API 7：查看历史记录
用途：用户查看历史生成记录。
GET /mcp/api/tasks?type={image|video}&status={0|1|2|3}&page=1&limit=10
- type（可选）：image 或 video
- status（可选）：0=排队中 / 1=生成中 / 2=已完成 / 3=失败
- page（可选）：页码，默认 1
- limit（可选）：每页数量，默认 10，最大 20
- 返回字段：total、current_page、last_page、page_size、list 数组
API 8：MJ 绘画（MidJourney 风格）
用途：用户想用 MJ/MidJourney 风格绘画时调用。
调用决策树
当用户表达 [用MJ画] [MidJourney绘画] [MJ风格] 等意图时：
步骤 1：确认需求 IF 用户提供了描述： prompt = 用户的描述 ELSE： 询问用户："请描述您想要的图片效果" → 停止，等待用户回复
步骤 2：构建请求 POST /mcp/api/mj/draw
步骤 3：发送请求并处理响应 IF response 成功： serialNo = response.serial_no 说："✅ MJ 绘画任务已提交！正在生成中..." 转到 "API 5：查询任务状态" 流程 ELSE： 转到 "错误处理" 流程
请求体字段
| 参数 | 必填 | 说明 |
|---|---|---|
| prompt | 是 | 描述词，支持中英文混合，建议详细描述以获得更好效果 |
| model | 否 | 模型名称或 ID（默认 V6.1），先调 /mcp/api/models?type=mj 查看可用模型，直接传返回的名称或 ID |
| aspect_ratio | 否 | 1:1（默认）/ 1:2 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 |
| speed | 否 | normal / fast（默认）/ turbo（仅MJ7.0）/ draft（仅MJ7.0） |
| quality | 否 | 质量化 0~100，默认 100 |
| stylize | 否 | 风格化 0~1000，默认 100（MJ 7.0 不支持） |
| chaos | 否 | 多样化 0~100，默认 0 |
| iw | 否 | 图片权重 0.25~2.0，默认 1.25（仅有参考图时生效） |
| sref | 否 | 风格参考权重 |
| cref | 否 | 角色参考 |
| oref | 否 | 物体参考 |
| input_images | 否 | 参考图片数组（URL / base64） |
| public | 否 | 是否公开作品，默认 false |
API 9：MJ 后续操作
用途：对 MJ 四宫格图片执行放大、变幻等操作。
POST /mcp/api/mj/action
| 参数 | 必填 | 说明 |
|---|---|---|
| serial_no | 是 | 原始任务序列号 |
| action | 是 | 操作类型（见下方） |
操作类型：
- U1
U4：放大第14张图（左上=1，右上=2，左下=3，右下=4） - V1
V4：变幻第14张图 - REROLL：重新生成
- STRONG/SUBTLE：强/弱变幻
- ZOOM15/ZOOM20：缩放
- LEFT/RIGHT/UP/DOWN：平移
- EXTEND：扩展
API 10：MJ 视频
用途：MJ 视频生成（需要首帧图片）。
POST /mcp/api/mj/video
| 参数 | 必填 | 说明 |
|---|---|---|
| prompt | 是 | 视频描述 |
| image | 是 | 首帧图片（URL / base64） |
| speed | 否 | normal（默认）/ fast |
| count | 否 | 视频数量 1（默认）/ 2 / 4 |
| motion | 否 | 动作幅度 low（默认）/ high |
| loop | 否 | 是否循环，默认 false |
| end_image | 否 | 尾帧图片 |
API 11：MJ 图生文
用途：上传图片获取 MJ 风格描述词。
POST /mcp/api/mj/describe
| 参数 | 必填 | 说明 |
|---|---|---|
| image | 是 | 图片（URL / base64） |
API 12：MJ 混图
用途：多图混合融合。
POST /mcp/api/mj/blend
| 参数 | 必填 | 说明 |
|---|---|---|
| images | 是 | 图片数组，至少 2 张（URL / base64） |
错误提示模板（必须原样使用，不准修改）
| HTTP 状态码 | 提示语 |
|---|---|
| 401/403 | "API Key 无效或已过期，请检查 MX_AI_API_KEY 配置" |
| 5xx | "请求服务器异常，请稍后重试" |
| 超时 | "请求超时，请稍后重试" |
| 网络错误 | "网络连接失败，请检查网络或代理设置" |
⚠️ 禁止使用其他表述，禁止添加"可能原因"、"建议检查"等额外内容。
详细错误日志输出（任何 HTTP 请求失败时必须执行）
除了展示上述用户友好的提示外，还必须输出详细的技术日志供排查问题。
需要输出的信息
| 类别 | 信息内容 | 说明 |
|---|---|---|
| 请求信息 | HTTP 方法 | GET/POST |
| URL（不含 query 参数） | 如 https://mcp.mxai.cn/mcp/api/user | |
| Header（隐藏 Authorization） | Authorization 显示为 Bearer nb_******** | |
| 请求体（隐藏 key） | 如有 key 相关字段，用 ******** 替换 | |
| 响应信息 | HTTP 状态码 | 如 401、500 |
| 响应头 | 完整展示 | |
| 响应体 | 完整展示，即使是错误信息 | |
| 错误信息 | 错误类型 | 如 NetworkError、TimeoutError |
| 错误消息 | 完整的错误文本 |
敏感信息隐藏规则
- Authorization: Bearer nb_xxxxxxxxxx → Authorization: Bearer nb_********
- 任何 nb_ 开头的字符串 → nb_********
- MX_AI_API_KEY 环境变量的完整值 → ********
日志输出格式
使用代码块包裹详细日志，格式如下：
=== 错误详情 === 请求：POST https://mcp.mxai.cn/mcp/api/generate/image 状态码：503 错误：请求服务器异常
--- 请求头 --- Content-Type: application/json Authorization: Bearer nb_********
--- 响应头 --- Content-Type: application/json
--- 响应体 --- {"error": "Service Unavailable", "message": "Please try again later"}
⚠️ 详细日志仅供技术排查，不要让普通用户误解。先展示用户友好提示，再展示详细日志。
版本
- Skill 版本: 1.4.3
- API 版本: 以 https://mcp.mxai.cn/mcp/skill/version 返回为准
- 兼容性: 不假设 API 格式固定，以实际响应为准
如果 API 响应包含未预期的字段，原样展示，不要报错。
升级提示：如果之前安装过旧版（文件夹名为 mx-ai-studio），请先删除旧文件夹再安装新版，避免两个 skill 共存冲突。
版本检查：GET https://mcp.mxai.cn/mcp/skill/version 如果 latest_version 高于 1.4.3，告知用户有新版本。