MiniMax CLI — Agent Skill Guide#

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

Prerequisites#

bash

# Install
npm install -g mmx-cli

# Auth (persisted to ~/.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.

---

Agent Flags#

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

FlagPurpose--non-interactiveFail fast on missing args instead of prompting--quietSuppress spinners/progress; stdout is pure data--output jsonMachine-readable JSON output--asyncReturn task ID immediately (video generation)--dry-runPreview the API request without executing--yesSkip confirmation prompts

---

Commands#

text chat#

Chat completion. Default model: MiniMax-M2.7.

bash

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

FlagTypeDescription--message <text>string, required, repeatableMessage text. Prefix with role: to set role (e.g. "system:You are helpful", "user:Hello")--messages-file <path>stringJSON file with messages array. Use - for stdin--system <text>stringSystem prompt--model <model>stringModel ID (default: MiniMax-M2.7)--max-tokens <n>numberMax tokens (default: 4096)--temperature <n>numberSampling temperature (0.0, 1.0]--top-p <n>numberNucleus sampling threshold--streambooleanStream tokens (default: on in TTY)--tool <json-or-path>string, repeatableTool definition JSON or file pathbash

# 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.

bash

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

FlagTypeDescription--prompt <text>string, requiredImage description--aspect-ratio <ratio>stringe.g. 16:9, 1:1``--n <count>numberNumber of images (default: 1)--subject-ref <params>stringSubject reference: type=character,image=path-or-url``--out-dir <dir>stringDownload images to directory--out-prefix <prefix>stringFilename prefix (default: image)bash

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.

bash

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

FlagTypeDescription--prompt <text>string, requiredVideo description--model <model>stringMiniMax-Hailuo-2.3 (default) or MiniMax-Hailuo-2.3-Fast``--first-frame <path-or-url>stringFirst frame image--callback-url <url>stringWebhook URL for completion--download <path>stringSave video to specific file--asyncbooleanReturn task ID immediately--no-waitbooleanSame as --async``--poll-interval <seconds>numberPolling interval (default: 5)bash

# 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.

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>]

---

speech synthesize#

Text-to-speech. Default model: speech-2.8-hd. Max 10k chars.

bash

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

FlagTypeDescription--text <text>stringText to synthesize--text-file <path>stringRead text from file. Use - for stdin--model <model>stringspeech-2.8-hd (default), speech-2.6, speech-02``--voice <id>stringVoice ID (default: English_expressive_narrator)--speed <n>numberSpeed multiplier--volume <n>numberVolume level--pitch <n>numberPitch adjustment--format <fmt>stringAudio format (default: mp3)--sample-rate <hz>numberSample rate (default: 32000)--bitrate <bps>numberBitrate (default: 128000)--channels <n>numberAudio channels (default: 1)--language <code>stringLanguage boost--subtitlesbooleanInclude subtitle timing data--pronunciation <from/to>string, repeatableCustom pronunciation--sound-effect <effect>stringAdd sound effect--out <path>stringSave audio to file--streambooleanStream raw audio to stdoutbash

mmx speech synthesize --text "Hello world" --out hello.mp3 --quiet
# stdout: hello.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]

FlagTypeDescription--prompt <text>stringMusic style description (can be detailed)--lyrics <text>stringSong lyrics with structure tags. Use "\u65e0\u6b4c\u8bcd" for instrumental. Cannot be used with --instrumental``--lyrics-file <path>stringRead lyrics from file. Use - for stdin--vocals <text>stringVocal style, e.g. "warm male baritone", "bright female soprano", "duet with harmonies"``--genre <text>stringMusic genre, e.g. folk, pop, jazz--mood <text>stringMood or emotion, e.g. warm, melancholic, uplifting--instruments <text>stringInstruments to feature, e.g. "acoustic guitar, piano"``--tempo <text>stringTempo description, e.g. fast, slow, moderate--bpm <number>numberExact tempo in beats per minute--key <text>stringMusical key, e.g. C major, A minor, G sharp--avoid <text>stringElements to avoid in the generated music--use-case <text>stringUse case context, e.g. "background music for video", "theme song"``--structure <text>stringSong structure, e.g. "verse-chorus-verse-bridge-chorus"``--references <text>stringReference tracks or artists, e.g. "similar to Ed Sheeran"``--extra <text>stringAdditional fine-grained requirements--instrumentalbooleanGenerate instrumental music (no vocals). Cannot be used with --lyrics or --lyrics-file``--aigc-watermarkbooleanEmbed AI-generated content watermark--format <fmt>stringAudio format (default: mp3)--sample-rate <hz>numberSample rate (default: 44100)--bitrate <bps>numberBitrate (default: 256000)--out <path>stringSave audio to file--streambooleanStream raw audio to stdout

At least one of --prompt or --lyrics is required.

bash

# 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)
mmx music generate --prompt "Cinematic orchestral, building tension" --instrumental --out bgm.mp3

---

vision describe#

Image understanding via VLM. Provide either --image or --file-id, not both.

bash

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

FlagTypeDescription--image <path-or-url>stringLocal path or URL (auto base64-encoded)--file-id <id>stringPre-uploaded file ID (skips base64)--prompt <text>stringQuestion 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).

---

search query#

Web search via MiniMax.

bash

mmx search query --q <query>

FlagTypeDescription--q <query>string, requiredSearch querybash

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

---

quota show#

Display Token Plan usage and remaining quotas.

bash

mmx quota show [--output json]

---

Tool Schema Export#

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

bash

# 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#

CodeMeaning0Success1General error2Usage error (bad flags, missing args)3Authentication error4Quota exceeded5Timeout10Content filter triggered

---

Piping Patterns#

bash

# 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.

bash

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

# Environment
export MINIMAX_API_KEY=sk-xxxxx
export MINIMAX_REGION=cn