mmx-quickstart

name	mmx.quickstart
description	Complete mmx CLI reference for agents — all commands, flags, auth/config precedence, exit codes, and dual-region setup.
tags	mmx,minimax,text,image,video,speech,music,vision,search,agent,quickstart

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:

1. --api-key flag
2. MINIMAX_API_KEY env var
3. ~/.mmx/credentials.json (stored OAuth/API key)
4. api_key in ~/.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

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