mmx-cli

MiniMax CLI — Agent 技能指南

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

前提条件

# Install
npm install -g mmx-cli

# Auth (persisted to ~/.mmx/credentials.json)
mmx auth login --api-key sk-xxxxx

# Or pass per-call
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	跳过确认提示

---

命令

文本聊天

聊天补全。默认模型：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 或文件路径

# Single message
mmx text chat --message "user:What is MiniMax?" --output json --quiet

# Multi-turn
mmx text chat \
  --system "You are a coding assistant." \
  --message "user:Write fizzbuzz in Python" \
  --output json

# From file
cat conversation.json | mmx text chat --messages-file - --output json

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

---

图像生成

生成图像。模型：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
# stdout: image URLs (one per line in quiet mode)

mmx image generate --prompt "Logo" --n 3 --out-dir ./gen/ --quiet
# stdout: saved file paths (one per line)

---

视频生成

生成视频。默认模型：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）

# Non-blocking: get task ID
mmx video generate --prompt "A robot." --async --quiet
# stdout: {"taskId":"..."}

# Blocking: wait and get file path
mmx video generate --prompt "Ocean waves." --download ocean.mp4 --quiet
# stdout: ocean.mp4

视频任务查询

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

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

视频下载

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

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

---

语音合成

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

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, repeatable	自定义发音
--sound-effect <effect>	string	添加音效
--out <path>	string	将音频保存到文件
--stream	boolean	将原始音频流式输出到标准输出

mmx speech synthesize --text "Hello world" --out hello.mp3 --quiet
# stdout: hello.mp3

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

---

生成音乐

生成音乐。模型：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	音乐流派，例如民谣、流行、爵士
--mood <text>	string	情绪或氛围，例如温暖、忧郁、振奋
--instruments <text>	string	突出的乐器，例如 "acoustic guitar, piano"
--tempo <text>	string	速度描述，例如快、慢、适中
--bpm <number>	number	精确速度，单位为每分钟节拍数
--key <text>	string	调性，例如 C 大调、A 小调、G 升调
--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 之一。

# Simple usage
mmx music generate --prompt "Upbeat pop" --lyrics "La la la..." --out song.mp3 --quiet

# Detailed prompt with vocal characteristics
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 (use --instrumental flag)
mmx music generate --prompt "Cinematic orchestral, building tension" --instrumental --out bgm.mp3

---

视觉描述

通过 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 模式）。

---

搜索查询

通过 MiniMax 进行网络搜索。

mmx search query --q <query>

标志	类型	说明
--q <query>	string, 必填	搜索查询

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

---

显示配额

显示 Token Plan 的用量和剩余配额。

mmx quota show [--output json]

---

工具架构导出

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

# All tool-worthy commands (excludes auth/config/update)
mmx config export-schema

# Single command
mmx config export-schema --command "video generate"

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

---

退出代码

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

---

管道模式

# stdout is always clean data — safe to pipe
mmx text chat --message "Hi" --output json | jq '.content'

# stderr has progress/spinners — discard if needed
mmx video generate --prompt "Waves" 2>/dev/null

# Chain: generate image → describe it
URL=$(mmx image generate --prompt "A sunset" --quiet)
mmx vision describe --image "$URL" --quiet

# Async video workflow
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 → 默认值。

# Persistent config
mmx config set --key region --value cn
mmx config show

# Environment
export MINIMAX_API_KEY=sk-xxxxx
export MINIMAX_REGION=cn