minimax-tokenplan-image-generation

# 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）

**第三步：填写配置**

获取以上信息后：
1. 修改 `scripts/generate.py` 顶部的配置常量（`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` |

---

## 快速使用

### 1️⃣ 文生图（Text-to-Image）

```bash
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`

**示例：**
```bash
# 生成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` 参数传入参考图：

```bash
python3 "$SKILL_DIR/scripts/generate.py" \
    --prompt "新的图片描述" \
    --image-url "/path/to/reference.jpg" \
    --aspect-ratio "9:16"
```

**--image-url 支持两种格式：**

1. **公网 URL**（直接使用，无需下载）
   ```bash
   --image-url "https://example.com/image.jpg"
   ```
   如果是 `http://` 或 `https://` 开头，直接传递给模型，不做下载和转换。

2. **本地文件路径**（转为 base64）
   ```bash
   --image-url "/path/to/reference.jpg"
   ```
   脚本会自动读取本地文件并转为 base64 Data URL 发送给 API。

**图生图规则：**
- `type` 固定为 `"character"`（保持人物/主体特征）
- 最多 1 张参考图
- **图片大小限制**：小于 10MB

**示例：**
```bash
# 以本地图片为参考（推荐方式）
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小时**） |

**示例：**
```bash
# 要求返回网络链接
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 是否正确 |