/minimax-multimodal-toolkit

name: minimax-multimodal-toolkit
description: Use mmx to generate text, images, video, and speech, and to transcribe audio, via the MiniMax AI platform. Use when the user wants to create media content, chat with MiniMax models, transcribe audio to text, perform web search, or manage MiniMax API resources from the terminal.

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

# 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.1-Flash`. An explicit `--model` or saved `default-text-model` takes precedence. This model currently requires M Plan or MiniMax Code; with a pay-as-you-go key, use `--model MiniMax-M3`. Thinking is enabled by default with `max` effort. See the [model guide](https://platform.minimax.io/docs/guides/text-generation#agent).

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.1-Flash`) | | `--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 or edit images with `MiniMax-H3-Image` (up to 20 MP). Always pass `--model MiniMax-H3-Image`. Use `--image` for image editing.

mmx image generate --model MiniMax-H3-Image --prompt <text> [flags]

| Flag | Type | Description | |---|---|---| | `--prompt <text>` | string, **required** | Image description | | `--model <model>` | string | Use `MiniMax-H3-Image` | | `--image <path-or-url>` | string, repeatable | 1–16 reference images → image editing (`/v1/images/edits`). Order = Picture 1, 2, … | | `--aspect-ratio <X:Y>` | string | `auto` (default) or X:Y (integers 1–300) between 1:3 and 3:1 | | `--area <level>` | string | `1K`, `2K`, `4K` (default) | | `--size <WxH>` | string | `auto` or e.g. `2720x1536`; area 655,360–20,000,000 px, ratio 1:3–3:1. Not with `--aspect-ratio`/`--area` | | `--n <count>` | number | 1–10 (default: 1) | | `--output-format <fmt>` | string | `jpg` (default), `png`, `webp` | | `--output-compression <q>` | number | 0–100 (default 95), jpg/webp only | | `--no-prompt-enhance` | boolean | Text-to-image only; needs `--size` or a concrete `--aspect-ratio` | | `--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`) | | `--out <path>` | string | Save a single image to an exact path | | `--aigc-watermark` | boolean | Embed AI-generated content watermark |

H3-Image is synchronous and **not idempotent** — do not re-run a command just because it was slow; each run is billed. Partial failures exit 0 with `failed_count`/`failures` in JSON output (failures are also printed to stderr, even with `--quiet`). With `--response-format base64`, the total area `n` × W × H is limited to 20 MP for png and 80 MP for jpg/webp (`size auto` counts the `--area` level, e.g. 4K = 4096×4096).

mmx image generate --model MiniMax-H3-Image --prompt "A cat on a windowsill" --aspect-ratio 16:9 --area 2K --output json --quiet
mmx image generate --model MiniMax-H3-Image --prompt "Put the hat from Picture 2 on the person in Picture 1" --image person.jpg --image hat.png --out result.jpg --quiet
mmx image generate --model MiniMax-H3-Image --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](https://github.com/MiniMax-AI/cli/blob/main/skill/h3-video/SKILL.md) instead.

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

| Flag | Type | Description | |---|---|---| | `--prompt <text>` | string, **required** | Video description | | `--model <model>` | string | `MiniMax-Hailuo-2.3` (default) or