skill.md

name: mmx-cli
description: 使用 mmx 通过 MiniMax AI 平台生成文本、图像、视频、语音和音乐。当用户想要创建媒体内容、与 MiniMax 模型聊天、执行网络搜索或从终端管理 MiniMax API 资源时使用。

MiniMax CLI — Agent 技能指南

使用 mmx 通过 MiniMax AI 平台生成文本、图像、视频、语音、音乐以及执行网页搜索。

前提条件

# 安装
npm install -g mmx-cli

# 认证（持久化到 ~/.mmx/credentials.json）
mmx auth login --api-key sk-xxxxx

# 或者每次调用时传递
mmx text chat --api-key sk-xxxxx --message "Hello"

区域自动检测。可使用 --region global 或 --region cn 覆盖。

---

Agent 标志

在非交互式（agent/CI）环境中始终使用这些标志：

标志	用途
`--non-interactive`	缺少参数时直接失败，而不是提示输入
`--quiet`	禁止旋转动画/进度条；标准输出为纯净数据
`--output json`	机器可读的 JSON 输出
`--async`	立即返回任务 ID（视频生成）
`--dry-run`	预览 API 请求而不执行
`--yes`	跳过确认提示

---

命令

text chat

聊天补全。默认模型：MiniMax-M2.7。

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

标志	类型	描述
`--message <text>`	string, 必填, 可重复	消息文本。以 `role:` 为前缀可设置角色（例如 `"system:You are helpful"`、`"user:Hello"`）
`--messages-file <path>`	string	包含消息数组的 JSON 文件。使用 `-` 表示标准输入
`--system <text>`	string	系统提示词
`--model <model>`	string	模型 ID（默认：`MiniMax-M2.7`）
`--max-tokens <n>`	number	最大令牌数（默认：4096）
`--temperature <n>`	number	采样温度（0.0, 1.0]
`--top-p <n>`	number	核采样阈值
`--stream`	boolean	流式输出令牌（默认：在 TTY 中开启）
`--tool <json-or-path>`	string, 可重复	工具定义 JSON 或文件路径

# 单条消息
mmx text chat --message "user:What is MiniMax?" --output json --quiet

# 多轮对话
mmx text chat \
  --system "You are a coding assistant." \
  --message "user:Write fizzbuzz in Python" \
  --output json

# 从文件读取
cat conversation.json | mmx text chat --messages-file - --output json

标准输出：响应文本（文本模式）或完整响应对象（JSON 模式）。

---

image generate

生成图像。模型：image-01。

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

标志	类型	描述
`--prompt <text>`	string, 必填	图像描述
`--aspect-ratio <ratio>`	string	例如 `16:9`、`1:1`
`--n <count>`	number	图像数量（默认：1）
`--subject-ref <params>`	string	对象参考：`type=character,image=path-or-url`
`--out-dir <dir>`	string	将图像下载到目录
`--out-prefix <prefix>`	string	文件名前缀（默认：`image`）

mmx image generate --prompt "A cat in a spacesuit" --output json --quiet
# 标准输出：图像 URL（安静模式下每行一个）

mmx image generate --prompt "Logo" --n 3 --out-dir ./gen/ --quiet
# 标准输出：保存的文件路径（每行一个）

---

video generate

生成视频。默认模型：MiniMax-Hailuo-2.3。这是一个异步任务——默认情况下会轮询直到完成。

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

标志	类型	描述
`--prompt <text>`	string, 必填	视频描述
`--model <model>`	string	`MiniMax-Hailuo-2.3`（默认）或 `MiniMax-Hailuo-2.3-Fast`
`--first-frame <path-or-url>`	string	首帧图像
`--callback-url <url>`	string	完成时的 Webhook URL
`--download <path>`	string	将视频保存到指定文件
`--async`	boolean	立即返回任务 ID
`--no-wait`	boolean	等同于 `--async`
`--poll-interval <seconds>`	number	轮询间隔（默认：5）

# 非阻塞：获取任务 ID
mmx video generate --prompt "A robot." --async --quiet
# 标准输出：{"taskId":"..."}

# 阻塞：等待并获取文件路径
mmx video generate --prompt "Ocean waves." --download ocean.mp4 --quiet
# 标准输出：ocean.mp4

video task get

查询视频生成任务的状态。

mmx video task get --task-id <id> [--output json]

video download

通过任务 ID 下载已完成的视频。

mmx video download --file-id <id> [--out <path>]

---

speech synthesize

文本转语音。默认模型：speech-2.8-hd。最多 1 万个字符。

mmx speech synthesize --text <text> [flags]

标志	类型	描述
`--text <text>`	string	要合成的文本
`--text-file <path>`	string	从文件读取文本。使用 `-` 表示标准输入
`--model <model>`	string	`speech-2.8-hd`（默认）、`speech-2.6`、`speech-02`
`--voice <id>`	string	语音 ID（默认：`English_expressive_narrator`）
`--speed <n>`	number	速度倍数
`--volume <n>`	number	音量级别
`--pitch <n>`	number	音调调整
`--format <fmt>`	string	音频格式（默认：`mp3`）
`--sample-rate <hz>`	number	采样率（默认：32000）
`--bitrate <bps>`	number	比特率（默认：128000）
`--channels <n>`	number	音频通道数（默认：1）
`--language <code>`	string	语言增强
`--subtitles`	boolean	包含字幕时间数据
`--pronunciation <from/to>`	string, 可重复	自定义发音
`--sound-effect <effect>`	string	添加音效
`--out <path>`	string	将音频保存到文件
`--stream`	boolean	将原始音频流式输出到标准输出

mmx speech synthesize --text "Hello world" --out hello.mp3 --quiet
# 标准输出：hello.mp3

echo "Breaking news." | mmx speech synthesize --text-file - --out news.mp3

---

music generate

生成音乐。模型：music-2.5。丰富的结构化描述效果更好。

mmx music generate --prompt <text> [--lyrics <text>] [flags]

标志	类型	描述
`--prompt <text>`	string	音乐风格描述（可以很详细）
`--lyrics <text>`	string	带结构标签的歌词。使用 `"\u65e0\u6b4c\u8bcd"` 表示纯器乐。不能与 `--instrumental` 同时使用
`--lyrics-file <path>`	string	从文件读取歌词。使用 `-` 表示标准输入
`--vocals <text>`	string	人声风格，例如 `"warm male baritone"`、`"bright female soprano"`、`"duet with harmonies"`
`--genre <text>`	string	音乐流派，例如 folk、pop、jazz
`--mood <text>`	string	情绪或情感，例如 warm、melancholic、uplifting
`--instruments <text>`	string	使用的乐器，例如 `"acoustic guitar, piano"`
`--tempo <text>`	string	速度描述，例如 fast、slow、moderate
`--bpm <number>`	number	精确速度（每分钟节拍数）
`--key <text>`	string	音乐调性，例如 C major、A minor、G sharp
`--avoid <text>`	string	生成音乐中要避免的元素
`--use-case <text>`	string	使用场景，例如 `"background music for video"`、`"theme song"`
`--structure <text>`	string	歌曲结构，例如 `"verse-chorus-verse-bridge-chorus"`
`--references <text>`	string	参考曲目或艺术家，例如 `"similar to Ed Sheeran"`
`--extra <text>`	string	其他细粒度要求
`--instrumental`	boolean	生成纯器乐（无演唱）。不能与 `--lyrics` 或 `--lyrics-file` 同时使用
`--aigc-watermark`	boolean	嵌入 AI 生成内容水印
`--format <fmt>`	string	音频格式（默认：`mp3`）
`--sample-rate <hz>`	number	采样率（默认：44100）
`--bitrate <bps>`	number	比特率（默认：256000）
`--out <path>`	string	将音频保存到文件
`--stream`	boolean	将原始音频流式输出到标准输出

--prompt 和 --lyrics 至少需要一个。

# 简单用法
mmx music generate --prompt "Upbeat pop" --lyrics "La la la..." --out song.mp3 --quiet

# 带人声特征的详细提示
mmx music generate --prompt "Warm morning folk" \
  --vocals "male and female duet, harmonies in chorus" \
  --instruments "acoustic guitar, piano" \
  --bpm 95 \
  --lyrics-file song.txt \
  --out duet.mp3

# 纯器乐（使用 --instrumental 标志）
mmx music generate --prompt "Cinematic orchestral, building tension" --instrumental --out bgm.mp3

---

vision describe

通过 VLM 进行图像理解。提供 --image 或 --file-id 之一，不能同时提供。

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

标志	类型	描述
`--image <path-or-url>`	string	本地路径或 URL（自动 base64 编码）
`--file-id <id>`	string	预上传的文件 ID（跳过 base64）
`--prompt <text>`	string	关于图像的问题（默认：`"Describe the image."`）

mmx vision describe --image photo.jpg --prompt "What breed?" --output json

标准输出：描述文本（文本模式）或完整响应（JSON 模式）。

---

search query

通过 MiniMax 进行网页搜索。

mmx search query --q <query>

标志	类型	描述
`--q <query>`	string, 必填	搜索查询

mmx search query --q "MiniMax AI" --output json --quiet

---

quota show

显示令牌计划的使用情况和剩余配额。

mmx quota show [--output json]

---

工具 Schema 导出

将所有命令导出为 Anthropic/OpenAI 兼容的 JSON 工具 schema：

# 所有适合作为工具的命令（排除 auth/config/update）
mmx config export-schema

# 单个命令
mmx config export-schema --command "video generate"

使用此功能可在您的 Agent 框架中动态注册 mmx 命令作为工具。

---

退出代码

代码	含义
0	成功
1	一般错误
2	用法错误（错误标志、缺少参数）
3	认证错误
4	配额超限
5	超时
10	内容过滤器触发

---

管道模式

# 标准输出始终是干净数据——可安全地通过管道传递
mmx text chat --message "Hi" --output json | jq '.content'

# 标准错误输出包含进度/旋转动画——可根据需要丢弃
mmx video generate --prompt "Waves" 2>/dev/null

# 链式操作：生成图像 → 描述它
URL=$(mmx image generate --prompt "A sunset" --quiet)
mmx vision describe --image "$URL" --quiet

# 异步视频工作流
TASK=$(mmx video generate --prompt "A robot" --async --quiet | jq -r '.taskId')
mmx video task get --task-id "$TASK" --output json
mmx video download --task-id "$TASK" --out robot.mp4

---

配置优先级

CLI 标志 → 环境变量 → ~/.mmx/config.json → 默认值。

# 持久化配置
mmx config set --key region --value cn
mmx config show

# 环境变量
export MINIMAX_API_KEY=sk-xxxxx
export MINIMAX_REGION=cn

mmx-cli

安装方式