javimosch mmx Quickstart
Use mmx to generate text, images, video, speech, music, and search via the MiniMax AI platform.
Install and Authenticate
# Install
npm install -g mmx-cli
# Authenticate with API key (persisted to ~/.mmx/credentials.json)
mmx auth login --api-key sk-xxxxx
# Or use environment variable (checked before stored credentials)
export MINIMAX_API_KEY=sk-xxxxx
Get API key: https://platform.minimax.io/subscribe/token-plan
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 |
Auth Precedence
Credentials are resolved in this order:
--api-keyflagMINIMAX_API_KEYenv var~/.mmx/credentials.json(stored OAuth/API key)api_keyin~/.mmx/config.yaml
Config Precedence
CLI flags → environment variables → ~/.mmx/config.json → defaults.
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Usage error (invalid arguments) |
| 3 | Authentication error |
| 4 | Quota exceeded |
| 5 | Timeout |
| 10 | Content filter triggered |
| 130 | Interrupted (Ctrl+C) |
mmx auth
# Login with API key
mmx auth login --api-key sk-xxxxx
# OAuth browser flow
mmx auth login
# Device-code flow (no browser)
mmx auth login --no-browser
# Check authentication status
mmx auth status
# Refresh OAuth token
mmx auth refresh
# Revoke and clear credentials
mmx auth logout
mmx text chat
Send a chat completion. Default model: MiniMax-M2.7.
mmx text chat --message <text> [flags]
| Flag | Type | Description |
|---|---|---|
--message |
string, repeatable | Message text. Prefix with role: to set role (user:, assistant:, system:) |
--messages-file |
string | JSON file with messages array (use - for stdin) |
--system |
string | System prompt |
--model |
string | Model ID (default: MiniMax-M2.7); also MiniMax-M2.7-highspeed |
--max-tokens |
integer | Max tokens to generate (default: 4096) |
--temperature |
number | Sampling temperature (0.0, 1.0] |
--top-p |
number | Nucleus sampling threshold |
--stream |
boolean | Stream tokens (default: on in TTY) |
--tool |
string, repeatable | Tool definition JSON or file path (for function calling) |
--output |
string | text (default) or json |
# Single message
mmx text chat --message "What is MiniMax?" --output json --quiet
# Multi-turn conversation
mmx text chat --message "user:Hi" --message "assistant:Hey!" --message "How are you?"
# With system prompt
mmx text chat --system "You are a coding assistant" --message "Write fizzbuzz in Go"
# From file
cat messages.json | mmx text chat --messages-file - --output json
# Streaming
mmx text chat --message "Tell me a story" --stream
mmx image generate
Generate images. Model: image-01.
mmx image generate --prompt <text> [flags]
| Flag | Type | Description |
|---|---|---|
--prompt |
string, required | Image description |
--aspect-ratio |
string | e.g. 16:9, 1:1, 9:16 |
--n |
integer | Number of images (default: 1) |
--seed |
integer | Random seed for reproducible output |
--width |
integer | Custom width in pixels (512–2048, multiple of 8) |
--height |
integer | Custom height in pixels (512–2048, multiple of 8) |
--prompt-optimizer |
boolean | Automatically optimize the prompt |
--aigc-watermark |
boolean | Embed AI-generated content watermark |
--subject-ref |
string | Subject reference: type=character,image=path-or-url |
--out-dir |
string | Download images to directory |
--out-prefix |
string | Filename prefix (default: image) |
--output |
string | text (default) or json |
# Simple
mmx image generate --prompt "A cat in a spacesuit" --output json --quiet
# Multiple with aspect ratio
mmx image generate --prompt "Mountain landscape" --n 3 --aspect-ratio 16:9
# To directory
mmx image generate --prompt "Logo" --out-dir ./out/ --quiet
mmx video generate
Generate video. Default model: MiniMax-Hailuo-2.3. Async by default — polls until completion unless --async is set.
mmx video generate --prompt <text> [flags]
| Flag | Type | Description |
|---|---|---|
--prompt |
string, required | Video description |
--model |
string | MiniMax-Hailuo-2.3 (default) or MiniMax-Hailuo-2.3-Fast |
--first-frame |
string | First frame image (I2V mode) |
--last-frame |
string | Last frame image (SEF mode, requires --first-frame) |
--subject-image |
string | Subject reference image (S2V mode) |
--callback-url |
string | Webhook URL for completion notification |
--download |
string | Save video to file on completion (blocking) |
--no-wait |
boolean | Return task ID immediately (same as --async) |
--async |
boolean | Return task ID immediately |
--poll-interval |
integer | Polling interval in seconds (default: 5) |
--output |
string | text (default) or json |
# Blocking: wait and get file path
mmx video generate --prompt "Ocean waves." --download ocean.mp4 --quiet
# Non-blocking: get task ID
mmx video generate --prompt "A robot." --async --quiet
# stdout: {"taskId":"..."}
# I2V: first frame
mmx video generate --prompt "Walk forward" --first-frame start.jpg
# S2V: subject reference
mmx video generate --prompt "A detective walking" --subject-image character.jpg
mmx video task get
Query status of a video generation task.
mmx video task get --task-id <id> [--output json]
mmx video download
Download a completed video by file ID.
mmx video download --file-id <id> --out <path> [--output json]
mmx speech synthesize
Text-to-speech. Default model: speech-2.8-hd. Max 10k chars.
mmx speech synthesize --text <text> [flags]
| Flag | Type | Description |
|---|---|---|
--text |
string | Text to synthesize |
--text-file |
string | Read text from file (use - for stdin) |
--model |
string | speech-2.8-hd (default), speech-2.6, speech-02 |
--voice |
string | Voice ID (default: English_expressive_narrator) |
--speed |
number | Speech speed multiplier |
--volume |
number | Volume level |
--pitch |
number | Pitch adjustment |
--format |
string | Audio format (default: mp3) |
--sample-rate |
integer | Sample rate (default: 32000) |
--bitrate |
integer | Bitrate (default: 128000) |
--channels |
integer | Audio channels (default: 1) |
--language |
string | Language boost |
--subtitles |
boolean | Include subtitle timing data |
--pronunciation |
string, repeatable | Custom pronunciation (format: from/to) |
--out |
string | Save audio to file |
--stream |
boolean | Stream raw audio to stdout |
--output |
string | text (default) or json |
# Simple
mmx speech synthesize --text "Hello world" --out hello.mp3 --quiet
# Voice and speed
mmx speech synthesize --text "Hi" --voice English_magnetic_voiced_man --speed 1.2
# From stdin
echo "Breaking news" | mmx speech synthesize --text-file - --out news.mp3
# Streaming audio
mmx speech synthesize --text "Stream me" --stream | mpv -
mmx speech voices
List available system voices.
mmx speech voices [--language <lang>] [--output json]
mmx music generate
Generate a song. Model: music-2.6-free (unlimited for API key users, RPM=3).
mmx music generate [--prompt <text>] [--lyrics <text>] [flags]
| Flag | Type | Description |
|---|---|---|
--prompt |
string | Music style description |
--lyrics |
string | Song lyrics with structure tags |
--lyrics-file |
string | Read lyrics from file (use - for stdin) |
--lyrics-optimizer |
boolean | Auto-generate lyrics from prompt |
--instrumental |
boolean | Generate instrumental (no vocals) |
--vocals |
string | Vocal style (e.g. "warm male baritone", "bright female soprano") |
--genre |
string | Music genre |
--mood |
string | Mood or emotion |
--instruments |
string | Instruments to feature |
--tempo |
string | Tempo description (fast, slow, moderate) |
--bpm |
integer | Exact tempo in BPM |
--key |
string | Musical key (e.g. C major) |
--avoid |
string | Elements to avoid |
--use-case |
string | Use case context (e.g. "background music for video") |
--structure |
string | Song structure (e.g. verse-chorus-verse-bridge-chorus) |
--references |
string | Reference tracks or artists |
--extra |
string | Additional fine-grained requirements |
--aigc-watermark |
boolean | Embed AI-generated content watermark |
--format |
string | Audio format (default: mp3) |
--sample-rate |
integer | Sample rate (default: 44100) |
--bitrate |
integer | Bitrate (default: 256000) |
--stream |
boolean | Stream raw audio to stdout |
--out |
string | Save audio to file |
--output |
string | text (default) or json |
At least one of --prompt or --lyrics is required.
# With lyrics
mmx music generate --prompt "Upbeat pop" --lyrics "[verse] La da dee..." --out song.mp3 --quiet
# Auto-generate lyrics
mmx music generate --prompt "Upbeat pop about summer" --lyrics-optimizer --out summer.mp3
# Instrumental
mmx music generate --prompt "Cinematic orchestral, building tension" --instrumental --out bgm.mp3
# Detailed
mmx music generate --prompt "Warm morning folk" \
--vocals "male and female duet, harmonies" \
--instruments "acoustic guitar, piano" \
--bpm 95 --out duet.mp3
mmx music cover
Generate a cover version of a song. Model: music-cover-free (unlimited, RPM=3).
mmx music cover --prompt <text> (--audio <url> | --audio-file <path>) [flags]
| Flag | Type | Description |
|---|---|---|
--prompt |
string, required | Target cover style |
--audio |
string | URL of reference audio (6s–6min, max 50MB) |
--audio-file |
string | Local reference audio file |
--lyrics |
string | Cover lyrics (if omitted, extracted via ASR) |
--lyrics-file |
string | Read lyrics from file |
--seed |
integer | Random seed 0–1000000 for reproducible results |
--format |
string | Audio format: mp3, wav, pcm (default: mp3) |
--sample-rate |
integer | Sample rate (default: 44100) |
--bitrate |
integer | Bitrate (default: 256000) |
--channel |
integer | Channels: 1 (mono) or 2 (stereo) |
--stream |
boolean | Stream raw audio to stdout |
--out |
string | Save audio to file |
--output |
string | text (default) or json |
# Cover from URL
mmx music cover --prompt "Indie folk, acoustic guitar" \
--audio https://example.com/song.mp3 --out cover.mp3 --quiet
# From local file
mmx music cover --prompt "Jazz, piano, slow" \
--audio-file original.mp3 --out jazz_cover.mp3
# Reproducible with seed
mmx music cover --prompt "Pop, upbeat" \
--audio https://example.com/song.mp3 --seed 42 --out cover.mp3
mmx vision describe
Image understanding via VLM.
mmx vision describe (--image <path-or-url> | --file-id <id>) [--prompt <text>] [--output json]
| Flag | Type | Description |
|---|---|---|
--image |
string | Local path or URL (auto base64-encoded) |
--file-id |
string | Pre-uploaded file ID |
--prompt |
string | Question about the image (default: "Describe the image.") |
Provide either --image or --file-id, not both.
mmx vision describe --image photo.jpg
mmx vision describe --image https://example.com/photo.jpg --prompt "What breed?"
mmx search query
Web search via MiniMax.
mmx search query --q <query> [--output json]
mmx search query --q "MiniMax AI latest news" --output json --quiet
mmx quota show
Display Token Plan usage and remaining quotas.
mmx quota show [--output json]
mmx config
# Show current configuration
mmx config show
# Set a config value
mmx config set --key region --value cn
# Valid keys: region, base_url, output, timeout, api_key
# Valid regions: global, cn
# Export config schema as JSON
mmx config export-schema [--command "video generate"]
Dual Region
- Global (default):
--region global→api.minimax.io - CN:
--region cn→api.minimaxi.com
# Via CLI flag
mmx text chat --message "Hello" --region cn
# Persistent
mmx config set --key region --value cn