在终端、Agent 或 CI 中需要调用 MiniMax…

适用于已配置 MiniMax API Key 的开发者，通过 mmx 以非交互方式从命令行生成媒体、聊天、搜索、查配额并导出工具 schema。

适用场景

解决思路

1. 安装：运行 `npm install -g mmx-cli`。
2. 认证：运行 `mmx auth login --api-key sk-xxxxx`，凭证持久化到 `~/.mmx/credentials.json`；也可在每次调用时传 `--api-key sk-xxxxx`。
3. 区域自动检测，可用 `--region global` 或 `--region cn` 覆盖。
4. 在 Agent/CI 非交互上下文统一使用这些 flag：`--non-interactive` 缺参时快速失败不提示；`--quiet` 抑制 spinner/进度，stdout 为纯数据；`--output json` 输出机器可读 JSON；`--async` 视频生成立即返回 task ID；`--dry-run` 预览 API 请求不执行；`--yes` 跳过确认提示。
5. text chat：运行 `mmx text chat --message <text> [flags]`，默认模型 `MiniMax-M2.7`。`--message <text>` 必填且可重复，前缀 `role:` 设置角色，如 `system:You are helpful`、`user:Hello`；`--messages-file <path>` 读取 JSON messages 数组，`-` 表示 stdin；`--system <text>` 设置系统提示；`--model <model>` 指定模型；`--max-tokens <n>` 默认 4096；`--temperature <n>`；`--top-p <n>`；`--stream` 流式输出，TTY 默认开启；`--tool <json-or-path>` 可重复指定工具定义 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`。stdout 为响应文本或完整响应对象。
6. image generate：运行 `mmx image generate --prompt <text> [flags]`，模型为 `image-01`。`--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`。示例：`mmx image generate --prompt 'A cat in a spacesuit' --output json --quiet`，quiet 模式下 stdout 为图片 URL 每行一个；`mmx image generate --prompt 'Logo' --n 3 --out-dir ./gen/ --quiet`，stdout 为保存文件路径每行一个。
7. video generate：运行 `mmx video generate --prompt <text> [flags]`，默认模型 `MiniMax-Hailuo-2.3`，这是异步任务，默认轮询到完成。`--prompt <text>` 必填；`--model <model>` 可选 `MiniMax-Hailuo-2.3` 或 `MiniMax-Hailuo-2.3-Fast`；`--first-frame <path-or-url>` 指定首帧图；`--callback-url <url>` 设置完成 webhook；`--download <path>` 保存视频到指定文件；`--async` 立即返回 task ID；`--no-wait` 同 `--async`；`--poll-interval <seconds>` 默认 5。示例：非阻塞 `mmx video generate --prompt 'A robot.' --async --quiet`，stdout 为 `{'taskId':'...'}`；阻塞 `mmx video generate --prompt 'Ocean waves.' --download ocean.mp4 --quiet`，stdout 为 `ocean.mp4`。
8. video task get：运行 `mmx video task get --task-id <id> [--output json]` 查询视频生成任务状态。
9. video download：运行 `mmx video download --file-id <id> [--out <path>]` 按任务 ID 下载已完成视频；管道示例中也使用 `--task-id`。
10. speech synthesize：运行 `mmx speech synthesize --text <text> [flags]`，默认模型 `speech-2.8-hd`，最大 10k 字符。`--text <text>` 指定文本；`--text-file <path>` 从文件读取文本，`-` 表示 stdin；`--model <model>` 可选 `speech-2.8-hd` 默认、`speech-2.6`、`speech-02`；`--voice <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` 流式输出原始音频到 stdout。示例：`mmx speech synthesize --text 'Hello world' --out hello.mp3 --quiet`，stdout 为 `hello.mp3`；`echo 'Breaking news.' | mmx speech synthesize --text-file - --out news.mp3`。
11. music generate：运行 `mmx music generate --prompt <text> [--lyrics <text>] [flags]`，模型 `music-2.5`，对丰富结构化描述响应更好。`--prompt <text>` 音乐风格描述；`--lyrics <text>` 带结构标签的歌词，传 `无歌词` 表示纯音乐，不能与 `--instrumental` 同用；`--lyrics-file <path>` 从文件读取歌词，`-` 表示 stdin；`--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>` 精确 BPM；`--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>` 参考曲目或艺人；`--extra <text>` 额外细粒度要求；`--instrumental` 生成纯音乐，不能与 `--lyrics` 或 `--lyrics-file` 同用；`--aigc-watermark` 嵌入 AI 生成水印；`--format <fmt>` 默认 `mp3`；`--sample-rate <hz>` 默认 44100；`--bitrate <bps>` 默认 256000；`--out <path>` 保存音频；`--stream` 流式输出原始音频到 stdout。`--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`；纯音乐 `mmx music generate --prompt 'Cinematic orchestral, building tension' --instrumental --out bgm.mp3`。
12. vision describe：运行 `mmx vision describe (--image <path-or-url> | --file-id <id>) [flags]`，通过 VLM 做图像理解。`--image <path-or-url>` 本地路径或 URL，会自动 base64 编码；`--file-id <id>` 预上传文件 ID，跳过 base64；两者只能选一个。`--prompt <text>` 对图片提问，默认 `Describe the image.`。示例：`mmx vision describe --image photo.jpg --prompt 'What breed?' --output json`。stdout 为描述文本或完整响应。
13. search query：运行 `mmx search query --q <query>` 通过 MiniMax 做网页搜索。`--q <query>` 必填。示例：`mmx search query --q 'MiniMax AI' --output json --quiet`。
14. quota show：运行 `mmx quota show [--output json]` 显示 Token Plan 使用量和剩余配额。
15. Tool Schema Export：运行 `mmx config export-schema` 导出所有适合作为工具的 commands 为 Anthropic/OpenAI 兼容 JSON tool schemas，会排除 auth/config/update；运行 `mmx config export-schema --command 'video generate'` 导出单个 command。可用于在 agent 框架中动态注册 mmx commands 为工具。
16. Exit Codes：0 成功；1 通用错误；2 用法错误（坏 flag、缺参数）；3 认证错误；4 配额超出；5 超时；10 内容过滤触发。按退出码处理失败。
17. Piping 模式：stdout 始终为干净数据，可安全管道，如 `mmx text chat --message 'Hi' --output json | jq '.content'`；stderr 有进度/spinner，可丢弃如 `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`。
18. 配置优先级：CLI flags → 环境变量 → `~/.mmx/config.json` → 默认值。持久化配置：`mmx config set --key region --value cn`；`mmx config show`。环境变量：`export MINIMAX_API_KEY=sk-xxxxx`；`export MINIMAX_REGION=cn`。

适用边界 · 注意事项

• 没有 MiniMax API Key/账号，或无法联网访问 MiniMax 平台时不能用。
• 需要完全本地或开源模型、不能依赖第三方云服务或付费配额时不适合。
• 对内容过滤敏感且不能接受退出码 10 导致生成失败时需谨慎。