oc/skills/mmx/SKILL.md

---
name: mmx
description: MiniMax CLI (mmx) 技能索引。提供文本生成、语音合成、图像生成、视频生成、音乐生成、网络搜索、视觉理解等 AI 能力的命令行接口。当任务涉及 MiniMax API 调用、内容生成、或需要 AI 多模态能力时使用此技能。
---

# MiniMax CLI (mmx) Skill

MiniMax AI 多模态命令行工具，整合了 Text Generation、Speech Synthesis、Image Generation、Video Generation、Music Generation、Web Search、Vision 等能力。

## Global Flags

| Flag | 说明 |
|------|------|
| `--api-key <key>` | API Key (覆盖其他认证方式) |
| `--region <region>` | API 区域: `global` (默认) / `cn` |
| `--base-url <url>` | API Base URL (覆盖 region) |
| `--output <format>` | 输出格式: `text` / `json` |
| `--quiet` | 抑制非必要输出 |
| `--verbose` | 打印 HTTP 请求/响应详情 |
| `--timeout <seconds>` | 请求超时 (默认: 300) |
| `--no-color` | 禁用 ANSI 颜色和动画 |
| `--dry-run` | 显示将要执行的操作但不实际执行 |
| `--non-interactive` | 禁用交互式提示 (CI/agent 模式) |

## Resource Index

### 1. auth - 认证

| Command | 说明 |
|---------|------|
| `auth login` | 通过 OAuth 或 API Key 认证 |
| `auth status` | 显示当前认证状态和配额快照 |
| `auth refresh` | 手动刷新 OAuth Token |
| `auth logout` | 撤销 Token 并清除存储的凭据 |

#### auth login

```
mmx auth login [--api-key <key>] [--recommend] [--region=global|cn]
```

- `--api-key <key>` 直接保存 API Key
- `--recommend` 直接进入 OAuth (可配合 `--region=` 跳过区域选择)

#### auth status

```
mmx auth status
```

#### auth refresh

```
mmx auth refresh
```

#### auth logout

```
mmx auth logout [--yes] [--dry-run]
```

- `--yes` 跳过确认提示

---

### 2. text - 文本生成

| Command | 说明 |
|---------|------|
| `text chat` | 发送聊天补全 (MiniMax Messages API) |
| `text repl` | 启动交互式多轮对话会话 |

#### text chat

```
mmx text chat --message <text> [flags]
```

| Flag | 说明 | 默认值 |
|------|------|--------|
| `--model <model>` | 模型 ID | `MiniMax-M2.7` |
| `--message <text>` | 消息文本 (可重复, 前缀 `role:` 设置角色) | - |
| `--messages-file <path>` | JSON 文件包含消息数组 (`-` 表示 stdin) | - |
| `--system <text>` | 系统提示词 | - |
| `--max-tokens <n>` | 最大生成 Token 数 | 4096 |
| `--temperature <n>` | 采样温度 (0.0, 1.0] | - |
| `--top-p <n>` | 核采样阈值 | - |
| `--stream` | 流式响应 (TTY 中默认开启) | - |
| `--tool <json-or-path>` | 工具定义 (可重复) | - |

**Examples:**

```bash
mmx text chat --message "What is MiniMax?"
mmx text chat --model MiniMax-M2.7-highspeed --system "You are a coding assistant." --message "Write fizzbuzz in Python"
cat conversation.json | mmx text chat --messages-file - --stream
```

#### text repl

```
mmx text repl [flags]
```

| Flag | 说明 | 默认值 |
|------|------|--------|
| `--model <model>` | 模型 ID | `MiniMax-M2.7` |
| `--system <text>` | 系统提示词 | - |
| `--max-tokens <n>` | 每响应最大 Token 数 | 4096 |
| `--temperature <n>` | 采样温度 (0.0, 1.0] | - |
| `--top-p <n>` | 核采样阈值 | - |

**Examples:**

```bash
mmx text repl
mmx text repl --model MiniMax-M2.7-highspeed --system "You are a coding assistant."
```

---

### 3. speech - 语音合成

| Command | 说明 |
|---------|------|
| `speech synthesize` | 同步 TTS, 最多 10k 字符 (speech-2.8-hd / 2.6 / 02) |
| `speech generate` | synthesize 的别名 |
| `speech voices` | 列出可用的系统声音 |

#### speech synthesize

```
mmx speech synthesize --text <text> [--out <path>] [flags]
```

| Flag | 说明 | 默认值 |
|------|------|--------|
| `--model <model>` | 模型 ID | `speech-2.8-hd` |
| `--text <text>` | 要合成的文本 | - |
| `--text-file <path>` | 从文件读取文本 (`-` 表示 stdin) | - |
| `--voice <id>` | 声音 ID | `English_expressive_narrator` |
| `--speed <n>` | 语速倍数 | - |
| `--volume <n>` | 音量 | - |
| `--pitch <n>` | 音调调整 | - |
| `--format <fmt>` | 音频格式: `mp3`, `pcm`, `flac`, `wav`, `pcmu_raw`, `pcmu_wav`, `opus` | `mp3` |
| `--sample-rate <hz>` | 采样率 | `32000` |
| `--bitrate <bps>` | 比特率 | `128000` |
| `--channels <n>` | 声道数 | `1` |
| `--language <code>` | 语言增强 | - |
| `--subtitles` | 包含字幕时间数据 | - |
| `--pronunciation <from/to>` | 自定义发音 (可重复) | - |
| `--out <path>` | 保存音频到文件 | - |
| `--stream` | 流式输出原始音频到 stdout | - |

**Examples:**

```bash
mmx speech synthesize --text "Hello, world!"
mmx speech synthesize --text "Hello, world!" --out hello.mp3
echo "Breaking news." | mmx speech synthesize --text-file - --out news.mp3
mmx speech synthesize --text "Stream" --stream | mpv --no-terminal -
```

#### speech voices

```
mmx speech voices [--language <lang>]
```

| Flag | 说明 |
|------|------|
| `--language <lang>` | 按语言过滤声音 (如 `english`, `korean`, `japanese`) |

**Examples:**

```bash
mmx speech voices
mmx speech voices --language english
mmx speech voices --output json
```

---

### 4. image - 图像生成

| Command | 说明 |
|---------|------|
| `image generate` | 生成图像 (image-01 / image-01-live) |

#### image generate

```
mmx image generate --prompt <text> [flags]
```

| Flag | 说明 | 默认值 |
|------|------|--------|
| `--prompt <text>` | 图像描述 | - |
| `--aspect-ratio <ratio>` | 宽高比 (如 `16:9`, `1:1`) | - |
| `--n <count>` | 生成图像数量 | `1` |
| `--seed <n>` | 随机种子 (相同 seed + prompt = 相同输出) | - |
| `--width <px>` | 自定义宽度 [512, 2048], 必须是 8 的倍数 | - |
| `--height <px>` | 自定义高度 [512, 2048], 必须是 8 的倍数 | - |
| `--prompt-optimizer` | 自动优化提示词 | - |
| `--aigc-watermark` | 在输出图像中嵌入 AI 生成内容水印 | - |
| `--subject-ref <params>` | 主体参考 (角色一致性): `type=character,image=path-or-url` | - |
| `--out <path>` | 保存图像到指定路径 (仅单张) | - |
| `--response-format <format>` | 响应格式: `url` (下载), `base64` (嵌入) | `url` |
| `--out-dir <dir>` | 下载图像到目录 | - |
| `--out-prefix <prefix>` | 文件名前缀 | `image` |

**Examples:**

```bash
mmx image generate --prompt "A cat in a spacesuit on Mars" --aspect-ratio 16:9
mmx image generate --prompt "Logo design" --n 3 --out-dir ./generated/
mmx image generate --prompt "Mountain landscape" --quiet
mmx image generate --prompt "A castle" --seed 42
mmx image generate --prompt "Wide landscape" --width 1920 --height 1080
mmx image generate --prompt "sunset" --prompt-optimizer --aigc-watermark
mmx image generate --prompt "A cat" --out /tmp/cat.jpg
mmx image generate --prompt "A cat" --response-format base64
```

---

### 5. video - 视频生成

| Command | 说明 |
|---------|------|
| `video generate` | 生成视频 (T2V/I2V/SEF/S2V) |
| `video task get` | 查询视频任务状态 |
| `video download` | 通过 File ID 下载完成的视频 |

#### video generate

```
mmx video generate --prompt <text> [flags]
```

| Flag | 说明 |
|------|------|
| `--model <model>` | 模型: T2V 用 `MiniMax-Hailuo-2.3`; I2V 用 `MiniMax-Hailuo-2.3` (默认) 或 `MiniMax-Hailuo-2.3-Fast` (需要 `--first-frame`); 有 `--last-frame` 切换到 `Hailuo-02`; 有 `--subject-image` 切换到 `S2V-01` |
| `--prompt <text>` | 视频描述 |
| `--first-frame <path-or-url>` | 首帧图像 (本地路径或 URL) |
| `--last-frame <path-or-url>` | 末帧图像 (需要 `--first-frame`, 启用 SEF 模式) |
| `--subject-image <path-or-url>` | 主体参考图像 (角色一致性) |
| `--callback-url <url>` | 完成通知的 Webhook URL |
| `--download <path>` | 完成后保存视频到文件 |
| `--no-wait` / `--async` | 立即返回任务 ID，不等待 |
| `--poll-interval <seconds>` | 轮询间隔 (默认: 5) |

**Video Modes:**

| Mode | 说明 | 模型 |
|------|------|------|
| T2V | 文本转视频 | Hailuo-2.3 |
| I2V | 图像转视频 | Hailuo-2.3 (默认) / Hailuo-2.3-Fast |
| SEF | 首尾帧插值 | Hailuo-02 |
| S2V | 主体一致性视频 | S2V-01 |

**Examples:**

```bash
mmx video generate --prompt "A man reads a book. Static shot."
mmx video generate --prompt "Ocean waves at sunset." --download sunset.mp4
mmx video generate --prompt "A robot painting." --async --quiet
mmx video generate --prompt "Walk forward" --first-frame start.jpg --last-frame end.jpg
mmx video generate --prompt "A detective walking" --subject-image character.jpg
```

#### video task get

```
mmx video task get --task-id <id>
```

| Flag | 说明 |
|------|------|
| `--task-id <id>` | 视频生成任务 ID |

**Examples:**

```bash
mmx video task get --task-id 106916112212032
mmx video task get --task-id 106916112212032 --output json
```

#### video download

```
mmx video download --file-id <id> --out <path>
```

| Flag | 说明 |
|------|------|
| `--file-id <id>` | 要下载的文件 ID |
| `--out <path>` | 输出文件路径 |

**Examples:**

```bash
mmx video download --file-id 176844028768320 --out video.mp4
```

---

### 6. music - 音乐生成

| Command | 说明 |
|---------|------|
| `music generate` | 生成歌曲 (music-2.6 / music-2.5+ / music-2.5) |
| `music cover` | 基于参考音频生成歌曲的翻唱版本 (music-cover) |

#### music generate

```
mmx music generate --prompt <text> (--lyrics <text> | --instrumental | --lyrics-optimizer) [--out <path>] [flags]
```

| Flag | 说明 | 默认值 |
|------|------|--------|
| `--prompt <text>` | 音乐风格描述 (最多 2000 字符) | - |
| `--lyrics <text>` | 带结构标签的歌词 | - |
| `--lyrics-file <path>` | 从文件读取歌词 (`-` 表示 stdin) | - |
| `--lyrics-optimizer` | 从 prompt 自动生成歌词 (不能与 `--lyrics` 或 `--instrumental` 共用) | - |
| `--instrumental` | 生成器乐音乐 | - |
| `--vocals <text>` | 人声风格, 如 "warm male baritone" | - |
| `--genre <text>` | 音乐流派, 如 folk, pop, jazz, electronic | - |
| `--mood <text>` | 情绪, 如 warm, melancholic, uplifting | - |
| `--instruments <text>` | 要突出的乐器 | - |
| `--tempo <text>` | 节奏描述, 如 fast, slow, moderate | - |
| `--bpm <number>` | 精确 BPM | - |
| `--key <text>` | 调性, 如 C major, A minor | - |
| `--avoid <text>` | 要避免的元素 | - |
| `--use-case <text>` | 使用场景, 如 "background music for video" | - |
| `--structure <text>` | 歌曲结构 | - |
| `--references <text>` | 参考曲目或艺术家 | - |
| `--extra <text>` | 额外细化需求 | - |
| `--model <model>` | 模型: `music-2.6` (默认), `music-2.5+`, `music-2.5` | `music-2.6` |
| `--output-format <fmt>` | 返回格式: `hex` (默认, 保存到文件) 或 `url` (24h 过期) | `hex` |
| `--aigc-watermark` | 嵌入 AI 生成内容水印 | - |
| `--format <fmt>` | 音频格式: `mp3`, `wav`, `pcm` | `mp3` |
| `--sample-rate <hz>` | 采样率 | `44100` |
| `--bitrate <bps>` | 比特率 | `256000` |
| `--stream` | 流式输出原始音频到 stdout | - |
| `--out <path>` | 保存音频到文件 | - |

**Lyrics 结构标签:**

`[Intro]`, `[Verse]`, `[Pre Chorus]`, `[Chorus]`, `[Interlude]`, `[Bridge]`, `[Outro]`, `[Post Chorus]`, `[Transition]`, `[Break]`, `[Hook]`, `[Build Up]`, `[Inst]`, `[Solo]`

**Examples:**

```bash
mmx music generate --prompt "Upbeat pop" --lyrics "La la la..." --out summer.mp3
mmx music generate --prompt "Indie folk, melancholic" --lyrics-file song.txt --out my_song.mp3
mmx music generate --prompt "Upbeat pop about summer" --lyrics-optimizer --out summer.mp3
mmx music generate --prompt "Cinematic orchestral, building tension" --instrumental --out bgm.mp3
mmx music generate --prompt "Upbeat pop" --lyrics "La la la..." --output-format url
mmx music generate --prompt "Warm morning folk" --vocals "male and female duet, harmonies in chorus" --instruments "acoustic guitar, piano" --bpm 95 --out duet.mp3
```

#### music cover

```
mmx music cover --prompt <text> (--audio <url> | --audio-file <path>) [--lyrics <text>] [--out <path>] [flags]
```

| Flag | 说明 | 默认值 |
|------|------|--------|
| `--model <model>` | 模型: `music-cover` (默认) | `music-cover` |
| `--prompt <text>` | 目标翻唱风格, 如 "Indie folk, acoustic guitar, warm male vocal" | - |
| `--audio <url>` | 参考音频 URL (mp3/wav/flac, 6s-6min, 最大 50MB) | - |
| `--audio-file <path>` | 本地参考音频文件 (自动 Base64 编码) | - |
| `--lyrics <text>` | 翻唱歌词 (省略则通过 ASR 从参考音频提取) | - |
| `--lyrics-file <path>` | 从文件读取歌词 (`-` 表示 stdin) | - |
| `--seed <number>` | 随机种子 0-1000000 | - |
| `--format <fmt>` | 音频格式: `mp3`, `wav`, `pcm` | `mp3` |
| `--sample-rate <hz>` | 采样率 | `44100` |
| `--bitrate <bps>` | 比特率 | `256000` |
| `--channel <n>` | 声道: `1` (单声道) / `2` (立体声, 默认) | `2` |
| `--stream` | 流式输出原始音频到 stdout | - |
| `--out <path>` | 保存音频到文件 | - |

**Examples:**

```bash
mmx music cover --prompt "Indie folk, acoustic guitar, warm male vocal" --audio https://example.com/song.mp3 --out cover.mp3
mmx music cover --prompt "Jazz, piano, slow" --audio-file original.mp3 --lyrics-file lyrics.txt --out jazz_cover.mp3
mmx music cover --prompt "Pop, upbeat" --audio https://example.com/ref.mp3 --seed 42 --out reproducible.mp3
```

---

### 7. search - 网络搜索

| Command | 说明 |
|---------|------|
| `search query` | 通过 MiniMax 搜索网页 |
| `search web` | `search query` 的别名 |

#### search query

```
mmx search query --q <query>
```

| Flag | 说明 |
|------|------|
| `--q <query>` | 搜索查询字符串 |

**Examples:**

```bash
mmx search query --q "MiniMax AI"
mmx search query --q "latest news" --output json
```

---

### 8. vision - 视觉理解

| Command | 说明 |
|---------|------|
| `vision describe` | 使用 MiniMax VLM 描述图像 |

#### vision describe

```
mmx vision describe (--image <path-or-url> | --file-id <id>) [--prompt <text>]
```

| Flag | 说明 | 默认值 |
|------|------|--------|
| `--image <path-or-url>` | 本地图像路径或 URL (自动 Base64 编码) | - |
| `--file-id <id>` | 预上传的文件 ID (跳过 Base64 转换) | - |
| `--prompt <text>` | 关于图像的问题 | `"Describe the image."` |

**Examples:**

```bash
mmx vision describe --image photo.jpg
mmx vision describe --image https://example.com/photo.jpg --prompt "What breed is this dog?"
mmx vision describe --file-id file-123456789 --prompt "Extract the text"
```

---

### 9. quota - 使用配额

| Command | 说明 |
|---------|------|
| `quota show` | 显示 Token Plan 使用情况和剩余配额 |

#### quota show

```
mmx quota show
```

**Examples:**

```bash
mmx quota show
mmx quota show --output json
```

---

### 10. config - CLI 配置

| Command | 说明 |
|---------|------|
| `config show` | 显示当前配置 |
| `config set` | 设置配置值 |
| `config export-schema` | 导出 CLI 命令为 Anthropic/OpenAI 兼容的 JSON 工具模式 |

#### config show

```
mmx config show
```

**Examples:**

```bash
mmx config show
mmx config show --output json
```

#### config set

```
mmx config set --key <key> --value <value>
```

| Flag | 说明 |
|------|------|
| `--key <key>` | 配置键: `region`, `base_url`, `output`, `timeout`, `api_key`, `proxy`, `default_text_model`, `default_speech_model`, `default_video_model`, `default_music_model` |
| `--value <value>` | 要设置的值 |

**Examples:**

```bash
mmx config set --key output --value json
mmx config set --key timeout --value 600
mmx config set --key proxy --value http://127.0.0.1:7890
mmx config set --key base_url --value https://api-uw.minimax.io
```

#### config export-schema

```
mmx config export-schema [--command "<name>"]
```

| Flag | 说明 |
|------|------|
| `--command <name>` | 仅导出特定命令的模式 (如 `video generate`) |

**Examples:**

```bash
mmx config export-schema
mmx config export-schema --command "video generate"
```

---

### 11. file - 文件存储

| Command | 说明 |
|---------|------|
| `file upload` | 上传文件到 MiniMax 存储 |
| `file list` | 列出已上传的文件 |
| `file delete` | 删除已上传的文件 |

#### file upload

```
mmx file upload --file <path> [--purpose <purpose>]
```

| Flag | 说明 | 默认值 |
|------|------|--------|
| `--file <path>` | 文件的本地路径 | - |
| `--purpose <string>` | 文件用途 (默认: `retrieval`) | `retrieval` |

**Examples:**

```bash
mmx file upload --file doc.pdf
mmx file upload --file image.png --purpose vision
```

#### file list

```
mmx file list
```

**Examples:**

```bash
mmx file list
mmx file list --output json
```

#### file delete

```
mmx file delete --file-id <id>
```

| Flag | 说明 |
|------|------|
| `--file-id <id>` | 要删除的文件 ID |

**Examples:**

```bash
mmx file delete --file-id 123456789
```

---

### 12. update - 更新

```
mmx update
```

更新 mmx 到最新版本。

---

## Quick Reference

```bash
# 认证
mmx auth login --api-key sk-cp-xxxxx
mmx auth status

# 文本生成
mmx text chat --message "Hello"

# 语音合成
mmx speech synthesize --text "Hello" --out hello.mp3

# 图像生成
mmx image generate --prompt "A sunset" --aspect-ratio 16:9

# 视频生成
mmx video generate --prompt "A man walking" --async --quiet

# 音乐生成
mmx music generate --prompt "Upbeat pop" --lyrics "La la" --out song.mp3

# 网络搜索
mmx search query --q "MiniMax"

# 视觉理解
mmx vision describe --image photo.jpg

# 查看配额
mmx quota show
```

## API Reference

- Text: https://platform.minimaxi.com/docs/api-reference/text-post
- Speech: https://platform.minimaxi.com/docs/api-reference/speech-t2a-http
- Image: https://platform.minimaxi.com/docs/api-reference/image-generation-t2i
- Video: https://platform.minimaxi.com/docs/api-reference/video-generation
- Music: https://platform.minimaxi.com/docs/api-reference/music-generation