openclaw/minimax-tokenplan-image-generation

MiniMax Image Generation Skill

前置条件

• Python 3 已安装
• requests 库：pip3 install requests

init

需要初始化以下信息：

第一步：查找 API Key

按以下优先级查找 MiniMax API Key（优先使用 sk-cp- 开头的 key）：

1. 环境变量 MINIMAX_API_KEY
2. ~/.openclaw/openclaw.json 中的相关配置
3. ~/.openclaw/agents/<AGENT_ID>/agent/*.json 中的相关配置

如果以上位置均未找到，请向用户获取 API Key。

第二步：确认配置

向用户确认：

• API Key 是否正确
• 使用哪个区域：
  • CN：api.minimaxi.com（中国版，支持 image-01 + image-01-live）
  • Global：api.minimaxi.io（国际版，仅支持 image-01）

第三步：填写配置

获取以上信息后：

1. 修改 scripts/generate.py 顶部第 36-38 行的配置常量（API_KEY、BASE_URL、REGION），填入实际值
2. 同时更新下方 ## 配置 区段的表格，作为配置记录

第四步：清理

配置填写完成后，删除本 ## 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 | | REGION | <待填入> | CN 或 global | | 支持的模型 | — | image-01（两者）, image-01-live（仅 CN） |

---

模型自动判断逻辑

CN 区（--region CN）会根据 prompt 关键词自动选择模型：

| prompt 关键词 | 自动选择模型 | 说明 | |--------------|-------------|------| | "参考原图"、 手绘、卡通、漫画、动漫、动画、油画、蜡笔、素描、水彩、国画、插画、原画、art style、cartoon、anime... | image-01-live | 艺术风格增强 | | 写实、真实、逼真、照片、摄影、realistic、photorealistic... | image-01 | 写实风格 | | 无明确风格 | image-01 | 默认写实 |

Global 区（--region global）： 只能用 image-01，忽略艺术风格判断。

手动指定模型： 传 --model image-01 或 --model image-01-live 可覆盖自动判断。

---

快速使用

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 | | --model | ❌ | 模型：auto、image-01、image-01-live | auto | | --region | ❌ | 区域：CN（中国）或 global（国际） | CN | | --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 支持两种格式：

1. 公网 URL（直接使用，无需下载）

   --image-url "https://example.com/image.jpg"
   

   如果是 http:// 或 https:// 开头，直接传递给模型，不做下载和转换。

2. 本地文件路径（转为 base64）

   --image-url "/path/to/reference.jpg"
   

   脚本会自动读取本地文件并转为 base64 Data URL 发送给 API。

图生图规则：

• type 固定为 "character"（保持人物/主体特征）
• 最多 1 张参考图
• 模型选择：和文生图一样，根据 prompt 关键词自动判断 image-01 或 image-01-live（详见上方"模型自动判断逻辑"）
• 图片大小限制：小于 10MB

示例：

# 以本地图片为参考（推荐方式）
python3 generate.py \
    --prompt "机械外骨骼大龙虾，在太空中战斗" \
    --image-url "/path/to/my-lobster.jpg" \
    --aspect-ratio "9:16"

---

工作流总结

图生图完整流程

1. 用户提供参考图片
2. 脚本自动处理 → 读取图片 → 转为 base64 Data URL
3. 调用 API → subject_reference 传入 base64 数据
4. 生成新图 → 返回图片 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 是否正确 |