mmx-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MiniMax CLI — Agent Skill Guide

MiniMax CLI — Agent 技能指南

Use

mmx

to generate text, images, video, speech, music, and perform web search via the MiniMax AI platform.

通过MiniMax AI平台使用

mmx

生成文本、图像、视频、语音、音乐，还可以执行网页搜索。

Prerequisites

前置要求

bash

undefined

bash

undefined

Install

安装

npm install -g mmx-cli

Auth (persisted to ~/.mmx/credentials.json)

认证（信息会持久化保存到 ~/.mmx/credentials.json）

mmx auth login --api-key sk-xxxxx

Or pass per-call

也可以在每次调用时传入密钥

mmx text chat --api-key sk-xxxxx --message "Hello"


Region is auto-detected. Override with `--region global` or `--region cn`.

---

mmx text chat --api-key sk-xxxxx --message "Hello"


区域会自动检测，你可以通过`--region global`或者`--region cn`参数手动覆盖。

---

Agent Flags

Agent 专用参数

Always use these flags in non-interactive (agent/CI) contexts:

Flag	Purpose
`--non-interactive`	Fail fast on missing args instead of prompting
`--quiet`	Suppress spinners/progress; stdout is pure data
`--output json`	Machine-readable JSON output
`--async`	Return task ID immediately (video generation)
`--dry-run`	Preview the API request without executing
`--yes`	Skip confirmation prompts

在非交互式（Agent/CI）场景下请始终使用这些参数：

参数	用途
`--non-interactive`	缺少参数时直接快速报错退出，而不是提示用户输入
`--quiet`	关闭加载动画/进度提示，标准输出仅返回纯净数据
`--output json`	返回机器可读的JSON格式输出
`--async`	立即返回任务ID（适用于视频生成场景）
`--dry-run`	仅预览API请求内容，不实际执行
`--yes`	跳过确认提示

Commands

命令说明

text chat

Chat completion. Default model:

MiniMax-M2.7

bash

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

Flag	Type	Description
`--message <text>`	string, required, repeatable	Message text. Prefix with `role:` to set role (e.g. `"system:You are helpful"` , `"user:Hello"` )
`--messages-file <path>`	string	JSON file with messages array. Use `-` for stdin
`--system <text>`	string	System prompt
`--model <model>`	string	Model ID (default: `MiniMax-M2.7` )
`--max-tokens <n>`	number	Max tokens (default: 4096)
`--temperature <n>`	number	Sampling temperature (0.0, 1.0]
`--top-p <n>`	number	Nucleus sampling threshold
`--stream`	boolean	Stream tokens (default: on in TTY)
`--tool <json-or-path>`	string, repeatable	Tool definition JSON or file path

bash

undefined

对话补全功能，默认模型：

MiniMax-M2.7

。

bash

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

参数	类型	说明
`--message <text>`	字符串，必填，可重复传入	消息内容，添加 `role:` 前缀可设置角色（例如 `"system:You are helpful"` 、 `"user:Hello"` ）
`--messages-file <path>`	字符串	存储消息数组的JSON文件路径，传入 `-` 表示从标准输入读取
`--system <text>`	字符串	系统提示词
`--model <model>`	字符串	模型ID（默认值： `MiniMax-M2.7` ）
`--max-tokens <n>`	数字	最大Token数（默认值：4096）
`--temperature <n>`	数字	采样温度，取值范围(0.0, 1.0]
`--top-p <n>`	数字	核采样阈值
`--stream`	布尔值	流式返回Token（TTY模式下默认开启）
`--tool <json-or-path>`	字符串，可重复传入	工具定义JSON内容或文件路径

bash

undefined

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


**stdout**: response text (text mode) or full response object (json mode).

---

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


**标准输出**：文本模式下返回响应文本，JSON模式下返回完整响应对象。

---

image generate

Generate images. Model:

image-01

bash

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

Flag	Type	Description
`--prompt <text>`	string, required	Image description
`--aspect-ratio <ratio>`	string	e.g. `16:9` , `1:1`
`--n <count>`	number	Number of images (default: 1)
`--subject-ref <params>`	string	Subject reference: `type=character,image=path-or-url`
`--out-dir <dir>`	string	Download images to directory
`--out-prefix <prefix>`	string	Filename prefix (default: `image` )

bash

mmx image generate --prompt "A cat in a spacesuit" --output json --quiet

生成图像，使用模型：

image-01

。

bash

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

参数	类型	说明
`--prompt <text>`	字符串，必填	图像描述
`--aspect-ratio <ratio>`	字符串	例如 `16:9` 、 `1:1`
`--n <count>`	数字	生成图像数量（默认值：1）
`--subject-ref <params>`	字符串	主体参考： `type=character,image=path-or-url`
`--out-dir <dir>`	字符串	下载图像到指定目录
`--out-prefix <prefix>`	字符串	文件名前缀（默认值： `image` ）

bash

mmx image generate --prompt "A cat in a spacesuit" --output json --quiet

stdout: image URLs (one per line in quiet mode)

标准输出：图像URL，quiet模式下每行返回一个

mmx image generate --prompt "Logo" --n 3 --out-dir ./gen/ --quiet

stdout: saved file paths (one per line)

标准输出：保存的文件路径，每行返回一个

---

---

video generate

Generate video. Default model:

MiniMax-Hailuo-2.3

. This is an async task — by default it polls until completion.

bash

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

Flag	Type	Description
`--prompt <text>`	string, required	Video description
`--model <model>`	string	`MiniMax-Hailuo-2.3` (default) or `MiniMax-Hailuo-2.3-Fast`
`--first-frame <path-or-url>`	string	First frame image
`--callback-url <url>`	string	Webhook URL for completion
`--download <path>`	string	Save video to specific file
`--async`	boolean	Return task ID immediately
`--no-wait`	boolean	Same as `--async`
`--poll-interval <seconds>`	number	Polling interval (default: 5)

bash

undefined

生成视频，默认模型：

MiniMax-Hailuo-2.3

。这是异步任务，默认会轮询直到任务完成。

bash

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

参数	类型	说明
`--prompt <text>`	字符串，必填	视频描述
`--model <model>`	字符串	`MiniMax-Hailuo-2.3` （默认）或 `MiniMax-Hailuo-2.3-Fast`
`--first-frame <path-or-url>`	字符串	首帧图像路径或URL
`--callback-url <url>`	字符串	任务完成回调的Webhook URL
`--download <path>`	字符串	将视频保存到指定路径
`--async`	布尔值	立即返回任务ID
`--no-wait`	布尔值	功能和 `--async` 一致
`--poll-interval <seconds>`	数字	轮询间隔（默认值：5秒）

bash

undefined

Non-blocking: get task ID

非阻塞调用：获取任务ID

mmx video generate --prompt "A robot." --async --quiet

stdout: {"taskId":"..."}

标准输出：{"taskId":"..."}

Blocking: wait and get file path

阻塞调用：等待完成并返回文件路径

mmx video generate --prompt "Ocean waves." --download ocean.mp4 --quiet

stdout: ocean.mp4

标准输出：ocean.mp4

undefined

undefined

video task get

Query status of a video generation task.

bash

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

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

bash

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

video download

Download a completed video by task ID.

bash

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

根据任务ID下载已完成的视频。

bash

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

speech synthesize

Text-to-speech. Default model:

speech-2.8-hd

. Max 10k chars.

bash

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

Flag	Type	Description
`--text <text>`	string	Text to synthesize
`--text-file <path>`	string	Read text from file. Use `-` for stdin
`--model <model>`	string	`speech-2.8-hd` (default), `speech-2.6` , `speech-02`
`--voice <id>`	string	Voice ID (default: `English_expressive_narrator` )
`--speed <n>`	number	Speed multiplier
`--volume <n>`	number	Volume level
`--pitch <n>`	number	Pitch adjustment
`--format <fmt>`	string	Audio format (default: `mp3` )
`--sample-rate <hz>`	number	Sample rate (default: 32000)
`--bitrate <bps>`	number	Bitrate (default: 128000)
`--channels <n>`	number	Audio channels (default: 1)
`--language <code>`	string	Language boost
`--subtitles`	boolean	Include subtitle timing data
`--pronunciation <from/to>`	string, repeatable	Custom pronunciation
`--sound-effect <effect>`	string	Add sound effect
`--out <path>`	string	Save audio to file
`--stream`	boolean	Stream raw audio to stdout

bash

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

文本转语音功能，默认模型：

speech-2.8-hd

，最多支持1万字符。

bash

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

参数	类型	说明
`--text <text>`	字符串	待合成的文本
`--text-file <path>`	字符串	从文件读取文本，传入 `-` 表示从标准输入读取
`--model <model>`	字符串	`speech-2.8-hd` （默认）、 `speech-2.6` 、 `speech-02`
`--voice <id>`	字符串	音色ID（默认值： `English_expressive_narrator` ）
`--speed <n>`	数字	语速倍数
`--volume <n>`	数字	音量等级
`--pitch <n>`	数字	音调调整值
`--format <fmt>`	字符串	音频格式（默认值： `mp3` ）
`--sample-rate <hz>`	数字	采样率（默认值：32000）
`--bitrate <bps>`	数字	比特率（默认值：128000）
`--channels <n>`	数字	音频声道数（默认值：1）
`--language <code>`	字符串	语言优化
`--subtitles`	布尔值	包含字幕时间轴数据
`--pronunciation <from/to>`	字符串，可重复传入	自定义发音规则
`--sound-effect <effect>`	字符串	添加音效
`--out <path>`	字符串	保存音频到指定路径
`--stream`	布尔值	将原始音频流式输出到标准输出

bash

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

stdout: hello.mp3

标准输出：hello.mp3

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

---

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

---

music generate

Generate music. Model:

music-2.5

. Responds well to rich, structured descriptions.

bash

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

Flag	Type	Description
`--prompt <text>`	string	Music style description (can be detailed)
`--lyrics <text>`	string	Song lyrics with structure tags. Use `"\u65e0\u6b4c\u8bcd"` for instrumental. Cannot be used with `--instrumental`
`--lyrics-file <path>`	string	Read lyrics from file. Use `-` for stdin
`--vocals <text>`	string	Vocal style, e.g. `"warm male baritone"` , `"bright female soprano"` , `"duet with harmonies"`
`--genre <text>`	string	Music genre, e.g. folk, pop, jazz
`--mood <text>`	string	Mood or emotion, e.g. warm, melancholic, uplifting
`--instruments <text>`	string	Instruments to feature, e.g. `"acoustic guitar, piano"`
`--tempo <text>`	string	Tempo description, e.g. fast, slow, moderate
`--bpm <number>`	number	Exact tempo in beats per minute
`--key <text>`	string	Musical key, e.g. C major, A minor, G sharp
`--avoid <text>`	string	Elements to avoid in the generated music
`--use-case <text>`	string	Use case context, e.g. `"background music for video"` , `"theme song"`
`--structure <text>`	string	Song structure, e.g. `"verse-chorus-verse-bridge-chorus"`
`--references <text>`	string	Reference tracks or artists, e.g. `"similar to Ed Sheeran"`
`--extra <text>`	string	Additional fine-grained requirements
`--instrumental`	boolean	Generate instrumental music (no vocals). Cannot be used with `--lyrics` or `--lyrics-file`
`--aigc-watermark`	boolean	Embed AI-generated content watermark
`--format <fmt>`	string	Audio format (default: `mp3` )
`--sample-rate <hz>`	number	Sample rate (default: 44100)
`--bitrate <bps>`	number	Bitrate (default: 256000)
`--out <path>`	string	Save audio to file
`--stream`	boolean	Stream raw audio to stdout

At least one of

--prompt

--lyrics

is required.

bash

undefined

生成音乐，使用模型：

music-2.5

，对丰富的结构化描述响应效果更好。

bash

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

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

--prompt

和

--lyrics

至少需要传入其中一个。

bash

undefined

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)

纯音乐（使用--instrumental参数）

mmx music generate --prompt "Cinematic orchestral, building tension" --instrumental --out bgm.mp3

---

mmx music generate --prompt "Cinematic orchestral, building tension" --instrumental --out bgm.mp3

---

vision describe

Image understanding via VLM. Provide either

--image

--file-id

, not both.

bash

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

Flag	Type	Description
`--image <path-or-url>`	string	Local path or URL (auto base64-encoded)
`--file-id <id>`	string	Pre-uploaded file ID (skips base64)
`--prompt <text>`	string	Question about the image (default: `"Describe the image."` )

bash

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

stdout: description text (text mode) or full response (json mode).

通过VLM实现图像理解，

--image

和

--file-id

二选一传入，不可同时使用。

bash

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

参数	类型	说明
`--image <path-or-url>`	字符串	本地路径或URL（会自动进行base64编码）
`--file-id <id>`	字符串	已上传的文件ID（无需再进行base64编码）
`--prompt <text>`	字符串	关于图像的问题（默认值： `"Describe the image."` ）

bash

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

标准输出：文本模式下返回描述文本，JSON模式下返回完整响应。

search query

Web search via MiniMax.

bash

mmx search query --q <query>

Flag	Type	Description
`--q <query>`	string, required	Search query

bash

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

通过MiniMax执行网页搜索。

bash

mmx search query --q <query>

参数	类型	说明
`--q <query>`	字符串，必填	搜索查询词

bash

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

quota show

Display Token Plan usage and remaining quotas.

bash

mmx quota show [--output json]

展示Token套餐使用情况和剩余配额。

bash

mmx quota show [--output json]

Tool Schema Export

工具Schema导出

Export all commands as Anthropic/OpenAI-compatible JSON tool schemas:

bash

undefined

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

bash

undefined

All tool-worthy commands (excludes auth/config/update)

导出所有适合作为工具的命令（排除认证/配置/更新类命令）

mmx config export-schema

Single command

导出单个命令的Schema

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


Use this to dynamically register mmx commands as tools in your agent framework.

---

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


可用于将mmx命令动态注册为你的Agent框架中的工具。

---

Exit Codes

退出码

Code	Meaning
0	Success
1	General error
2	Usage error (bad flags, missing args)
3	Authentication error
4	Quota exceeded
5	Timeout
10	Content filter triggered

编码	含义
0	成功
1	通用错误
2	使用错误（参数错误、缺少参数）
3	认证错误
4	配额不足
5	超时
10	触发内容过滤

Piping Patterns

管道使用示例

bash

undefined

bash

undefined

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

---

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

---

Configuration Precedence

配置优先级

CLI flags → environment variables →

~/.mmx/config.json

→ defaults.

bash

undefined

CLI参数 → 环境变量 →

~/.mmx/config.json

→ 默认值。

bash

undefined

Persistent config

持久化配置

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

Environment

环境变量

export MINIMAX_API_KEY=sk-xxxxx export MINIMAX_REGION=cn

undefined

export MINIMAX_API_KEY=sk-xxxxx export MINIMAX_REGION=cn

undefined