jacardl MiniMax CLI — Agent Skill Guide
Use mmx to generate text, images, video, speech, music, and perform web search via the MiniMax AI platform.
Prerequisites
# Install
npm install -g mmx-cli
# Auth (OAuth persists to ~/.mmx/credentials.json, API key persists to ~/.mmx/config.json)
mmx auth login --api-key sk-xxxxx
# Verify active auth source
mmx auth status
# Or pass per-call
mmx text chat --api-key sk-xxxxx --message "Hello"
Region is auto-detected. Override with --region global or --region cn.
Agent Flags
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 |
Commands
text chat
Chat completion. Default model: MiniMax-M2.7.
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 |
# 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).
image generate
Generate images. Model: image-01.
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. Ignored if --width and --height are both set |
--n <count> |
number | Number of images (default: 1) |
--seed <n> |
number | Random seed for reproducible generation |
--width <px> |
number | Width in pixels (512–2048, multiple of 8). Requires --height |
--height <px> |
number | Height in pixels (512–2048, multiple of 8). Requires --width |
--prompt-optimizer |
boolean | Optimize prompt before generation |
--aigc-watermark |
boolean | Embed AI-generated content watermark |
--subject-ref <params> |
string | Subject reference: type=character,image=path-or-url |
--response-format <format> |
string | url (default) or base64. Base64 bypasses CDN download |
--out-dir <dir> |
string | Download images to directory |
--out-prefix <prefix> |
string | Filename prefix (default: 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)
video generate
Generate video. Default model: MiniMax-Hailuo-2.3. This is an async task — by default it polls until completion.
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) |
# 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
video task get
Query status of a video generation task.
mmx video task get --task-id <id> [--output json]
video download
Download a completed video by task ID.
mmx video download --file-id <id> [--out <path>]
speech synthesize
Text-to-speech. Default model: speech-2.8-hd. Max 10k chars.
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 | Download and save subtitles as .srt file (alongside --out audio file). API must support subtitles for the selected model. |
--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 |
mmx speech synthesize --text "Hello world" --out hello.mp3 --quiet
# stdout: hello.mp3
mmx speech synthesize --text "Hello" --subtitles --out hello.mp3
# saves hello.mp3 + hello.srt (SRT subtitle file)
echo "Breaking news." | mmx speech synthesize --text-file - --out news.mp3
music generate
Generate music. Responds well to rich, structured descriptions.
Model: music-2.6-free — unlimited for API key users, RPM = 3.
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. Required unless --instrumental or --lyrics-optimizer is used. |
--lyrics-file <path> |
string | Read lyrics from file. Use - for stdin |
--lyrics-optimizer |
boolean | Auto-generate lyrics from prompt. Cannot be used with --lyrics or --instrumental. |
--instrumental |
boolean | Generate instrumental music (no vocals). Cannot be used with --lyrics. |
--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 |
--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 or --lyrics is required.
# With lyrics
mmx music generate --prompt "Upbeat pop" --lyrics "La la la..." --out song.mp3 --quiet
# Auto-generate lyrics from prompt
mmx music generate --prompt "Upbeat pop about summer" --lyrics-optimizer --out summer.mp3 --quiet
# Instrumental
mmx music generate --prompt "Cinematic orchestral, building tension" --instrumental --out bgm.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
music cover
Generate a cover version of a song based on reference audio.
Model: music-cover-free — unlimited for API key users, RPM = 3.
mmx music cover --prompt <text> (--audio <url> | --audio-file <path>) [flags]
| Flag | Type | Description |
|---|---|---|
--prompt <text> |
string, required | Target cover style, e.g. "Indie folk, acoustic guitar, warm male vocal" |
--audio <url> |
string | URL of reference audio (mp3, wav, flac, etc. — 6s to 6min, max 50MB) |
--audio-file <path> |
string | Local reference audio file (auto base64-encoded) |
--lyrics <text> |
string | Cover lyrics. If omitted, extracted from reference audio via ASR. |
--lyrics-file <path> |
string | Read lyrics from file. Use - for stdin |
--seed <number> |
number | Random seed 0–1000000 for reproducible results |
--format <fmt> |
string | Audio format: mp3, wav, pcm (default: mp3) |
--sample-rate <hz> |
number | Sample rate (default: 44100) |
--bitrate <bps> |
number | Bitrate (default: 256000) |
--channel <n> |
number | Channels: 1 (mono) or 2 (stereo, default) |
--out <path> |
string | Save audio to file |
--stream |
boolean | Stream raw audio to stdout |
# Cover from URL
mmx music cover --prompt "Indie folk, acoustic guitar, warm male vocal" \
--audio https://filecdn.minimax.chat/public/d20eda57-2e36-45bf-9e12-82d9f2e69a86.mp3 --out cover.mp3 --quiet
# Cover from local file with custom lyrics
mmx music cover --prompt "Jazz, piano, slow" \
--audio-file original.mp3 --lyrics-file lyrics.txt --out jazz_cover.mp3 --quiet
# Reproducible result with seed
mmx music cover --prompt "Pop, upbeat" --audio https://filecdn.minimax.chat/public/d20eda57-2e36-45bf-9e12-82d9f2e69a86.mp3 --seed 42 --out cover.mp3
vision describe
Image understanding via VLM. Provide either --image or --file-id, not both.
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.") |
mmx vision describe --image photo.jpg --prompt "What breed?" --output json
stdout: description text (text mode) or full response (json mode).
search query
Web search via MiniMax.
mmx search query --q <query>
| Flag | Type | Description |
|---|---|---|
--q <query> |
string, required | Search query |
mmx search query --q "MiniMax AI" --output json --quiet
quota show
Display Token Plan usage and remaining quotas.
mmx quota show [--output json]
Tool Schema Export
Export all commands as Anthropic/OpenAI-compatible JSON tool schemas:
# All tool-worthy commands (excludes auth/config/update)
mmx config export-schema
# Single command
mmx config export-schema --command "video generate"
Use this to dynamically register mmx commands as tools in your agent framework.
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 |
Piping Patterns
# 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
Configuration Precedence
CLI flags → environment variables → ~/.mmx/config.json → defaults.
# Persistent config
mmx config set --key region --value cn
mmx config show
# Environment
export MINIMAX_API_KEY=sk-xxxxx
export MINIMAX_REGION=cn
Default Model Configuration
Set per-modality defaults so you don't need --model every time:
# Set defaults
mmx config set --key default-text-model --value MiniMax-M2.7-highspeed
mmx config set --key default-speech-model --value speech-2.8-hd
mmx config set --key default-video-model --value MiniMax-Hailuo-2.3
mmx config set --key default-music-model --value music-2.6
# Use without --model
mmx text chat --message "Hello"
mmx speech synthesize --text "Hello" --out hello.mp3
mmx video generate --prompt "Ocean waves"
mmx music generate --prompt "Upbeat pop" --instrumental
# --model still overrides per-call
mmx text chat --model MiniMax-M2.7 --message "Hello"
Resolution priority: --model flag > config default > hardcoded fallback.