mmx-cli

# MiniMax CLI — Agent Skill Guide Use `mmx` to generate text, images, video, speech, transcribe audio, and perform web search via the MiniMax AI platform. ## Prerequisites ```bash # 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-M3`. ```bash 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-M3`) | | `--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 | ```bash # 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] ``` | 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`) | ```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` (or `MiniMax-Hailuo-2.3-Fast` for fast mode with `--image`). This is an async task — by default it polls until completion. For `MiniMax-H3` — text-to-video, first/last-frame, multimodal reference image/video/audio generation, prompt construction, and failure handling — use the dedicated [mmx-h3-video skill](h3-video/SKILL.md) instead. ```bash 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` | | `--image <path-or-url>` | string | Input image for image-to-video | | `--last-frame <path-or-url>` | string | Optional ending image for frame interpolation (used with `--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) | ```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] ``` | 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 | ```bash 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 ``` --- ### speech transcribe Speech-to-text. Default model: `asr-1.0`. Accepts wav, aiff, flac, m4a, mp3, aac, opus, and ogg files up to 50 MB and 500 seconds. ```bash mmx speech transcribe --file <path> [flags] ``` | Flag | Type | Description | |---|---|---| | `--file <path>` | string | Audio file to transcribe (required; also accepted as a positional argument) | | `--model <model>` | string | `asr-1.0` (default) | | `--response-format <fmt>` | string | `json` (default), `verbose_json`, `srt`, `vtt` | | `--language <code>` | string | BCP-47 language hint (`zh`, `en`, `ja`, ...). Omit for automatic/mixed-language detection | | `--timestamp-level <level>` | string | `sentence` (default) or `word`; applies to `verbose_json` / `srt` / `vtt` | | `--stream` | boolean | Stream incremental text to stdout. Requires `--response-format json` | | `--out <path>` | string | Write the result to a file instead of stdout | ```bash mmx speech transcribe --file meeting.mp3 # stdout: transcript text mmx speech transcribe --file call.mp3 --language zh --output json # stdout: {"text":"...","duration":12.3,"trace_id":"..."} mmx speech transcribe --file talk.mp3 --response-format verbose_json --timestamp-level word --output json # stdout: adds n_speakers and word-level segments mmx speech transcribe --file talk.mp3 --response-format srt --out talk.srt # saves talk.srt; stdout: {"saved":".../talk.srt"} mmx speech transcribe --file long.mp3 --stream # stdout: text as it is recognized (add --output text when piping) ``` Notes: - `mmx speech recognize` is an alias for `mmx speech transcribe`. - `--stream` cannot be combined with `--out`; redirect stdout instead. - `--stream` prints deltas only in text output mode. stdout that is not a terminal defaults to `json` (as everywhere else in this CLI), which accumulates the streamed text into one JSON result — pass `--output text` to pipe streamed text, e.g. `mmx speech transcribe --file long.mp3 --stream --output text > transcript.txt`. - `srt` / `vtt` results are subtitle documents and are printed or saved verbatim. - Without `--out`, `--output json` prints the full API response for `json` / `verbose_json`. Plain-text output prints the transcript only, so add `--output json` to read `n_speakers` and `segments`. - A stream that ends without the API's final event raises a warning on stderr, since the transcript may be truncated. - Input validation (missing file, unsupported format, over 50 MB, `--stream` with a non-json format) fails before anything is uploaded; the API stays the authority for the 500 s duration limit and codec support. --- ### 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] ``` | 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."`) | ```bash