MiniMax Image Generation Skill
前置条件
- Python 3 已安装
- requests 库：
pip3 install requests
init
需要初始化以下信息：
第一步：获取 API Key
向用户获取 MiniMax API Key（sk-cp- 开头的 Token Plan key，或普通 API Key）。
第二步：确认配置
向用户确认：
- API Key 是否正确
- 使用哪个区域：
- CN：
api.minimaxi.com（中国版，支持 image-01 + image-01-live）
- Global：
api.minimaxi.io（国际版，仅支持 image-01）
第三步：填写配置
获取以上信息后：
- 修改
scripts/generate.py 顶部的配置常量（API_KEY、BASE_URL、REGION），填入实际值
- 同时更新下方
## 配置 区段的表格，作为配置记录
第四步：清理
配置填写完成后，删除本 ## init 区段（包括 ### 需要初始化以下信息 的全部内容），仅保留 ## 配置 区段。
配置
注意：
- Global（api.minimaxi.io）仅支持
image-01 模型，不支持 image-01-live
- CN（api.minimaxi.com）支持
image-01 和 image-01-live
| 配置项 | 值 | 说明 |
|---|
| MINIMAX_API_KEY | <待填入> | 初始化时替换为实际 key |
| BASE_URL | <待填入> | CN: https://api.minimaxi.com / Global: https://api.minimaxi.io |
快速使用
1️⃣ 文生图（Text-to-Image）
SKILL_DIR="~/.openclaw/workspace/skills/minimax-tokenplan-image-generation"
python3 "$SKILL_DIR/scripts/generate.py" \
--prompt "你的图片描述" \
--aspect-ratio "16:9"
注意：以下示例中 generate.py 均指 ~/.openclaw/workspace/skills/minimax-tokenplan-image-generation/scripts/generate.py 的完整路径。
参数说明：
| 参数 | 必填 | 说明 | 默认值 |
|---|
--prompt | ✅ | 图片描述，最长 1500 字符，超出会报错 | - |
--aspect-ratio | ❌ | 宽高比 | 16:9 |
--output | ❌ | 输出路径 | 自动生成 |
--n | ❌ | 生成数量（最大9） | 1 |
--api-key | ❌ | API Key（默认使用文件顶部配置） | - |
--base-url | ❌ | Base URL（默认使用文件顶部配置） | - |
--response-format | ❌ | 返回格式：base64（保存图片）或 url（返回链接，24小时有效） | base64 |
aspect_ratio 可选值： 16:9 / 9:16 / 1:1 / 3:2 / 2:3
示例：
# 生成16:9风景图
python3 generate.py --prompt "日出时分雪山倒映在湖面，温暖的金色光线" --aspect-ratio "16:9"
# 生成9:16竖版人像
python3 generate.py --prompt "未来风格的城市夜景，赛博朋克" --aspect-ratio "9:16"
2️⃣ 图生图（Image-to-Image）
在文生图基础上，添加 --image-url 参数传入参考图：
python3 "$SKILL_DIR/scripts/generate.py" \
--prompt "新的图片描述" \
--image-url "/path/to/reference.jpg" \
--aspect-ratio "9:16"
--image-url 支持两种格式：
-
公网 URL（直接使用，无需下载）
--image-url "https://example.com/image.jpg"
如果是 http:// 或 https:// 开头，直接传递给模型，不做下载和转换。
-
本地文件路径（转为 base64）
--image-url "/path/to/reference.jpg"
脚本会自动读取本地文件并转为 base64 Data URL 发送给 API。
图生图规则：
type 固定为 "character"（保持人物/主体特征）- 最多 1 张参考图
- 图片大小限制：小于 10MB
示例：
# 以本地图片为参考（推荐方式）
python3 generate.py \
--prompt "机械外骨骼大龙虾，在太空中战斗" \
--image-url "/path/to/my-lobster.jpg" \
--aspect-ratio "9:16"
工作流总结
图生图完整流程
- 用户提供参考图片
- 脚本自动处理 → 读取图片 → 转为 base64 Data URL
- 调用 API → subject_reference 传入 base64 数据
- 生成新图 → 返回图片 URL 或 base64
Prompt 处理规则
不传 --prompt-optimizer / --no-prompt-optimizer 时，脚本会自动判断（阈值：40 字符）：
| 情况 | 处理方式 |
|---|
| prompt < 40 字符（短描述） | 脚本自动开启 prompt_optimizer，丰富描述细节 |
| prompt ≥ 40 字符（长描述） | 脚本自动关闭 prompt_optimizer，保留用户原意 |
| 用户明确说「不要改prompt」/「保持原样」 | 传 --no-prompt-optimizer，强制关闭 |
| 用户明确要求优化 prompt | 传 --prompt-optimizer，强制开启 |
| 用户要求多张 | 设置 --n 4（最大9） |
水印规则
| 情况 | 处理方式 |
|---|
| 默认 | aigc_watermark: false |
| prompt 含「水印/版权/标识/logo/watermark/copyright」等关键词 | aigc_watermark: true 自动开启 |
response_format 规则
| 情况 | 处理方式 |
|---|
| 默认 | 使用 base64，脚本自动解码保存 PNG |
| 用户明确要求"返回链接"、"返回URL"、"给我网络地址"等 | 传 --response-format url（返回 URL，注意：链接有效期仅24小时） |
示例：
# 要求返回网络链接
python3 generate.py --prompt "大龙虾在太空中战斗" --response-format url
# 输出：https://...
# 注意：返回的 URL 只有 24 小时有效期
文件存储
- 默认保存到：
~/.openclaw/media/minimax/（多 Agent 共享目录）
- 文件名格式：
minimax-YYYY-MM-DD-<prompt_slug>.png
- prompt_slug：取 prompt 关键词，英文前6词 + 中文前3词，空格变
-
脚本输出格式
调用 generate.py 后，stdout 输出生成结果，格式如下：
| response_format | stdout 输出 | 示例 |
|---|
base64（默认） | 保存后的文件绝对路径 | /Users/x/.openclaw/media/minimax/minimax-2026-03-27-sunset.png |
url | 图片的公网 URL（24小时有效） | https://filecdn.minimax.chat/... |
多张图片（--n 2+） | 用 | 分隔 | path1.png | path2.png |
所有日志信息（[INFO]、[WARN]、[ERROR]）输出到 stderr，不会混入 stdout。
错误处理
| code | 含义 | 处理 |
|---|
| 0 | 成功 | 继续 |
| 1002 | 限流 | 提醒用户 API 限流中，建议稍后重试 |
| 1004 | 鉴权失败 | 检查 API Key |
| 1008 | 余额不足 | 提醒充值 |
| 1026 | 敏感词 | 换词后重试 |
| 2013 | 参数异常 | 检查入参（可能是 URL 格式不对） |
| 2049 | 无效 Key | 检查 Key 是否正确 |
