mmx-cli

MiniMax CLI — エージェントスキルガイド

mmx を使用して、MiniMax AI プラットフォーム経由でテキスト、画像、動画、音声、音楽を生成し、ウェブ検索を実行できます。

前提条件

# 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 global または --region cn で変更できます。

---

エージェント用フラグ

非対話型（エージェント／CI）環境では、常に以下のフラグを使用してください。

フラグ	用途
--non-interactive	引数が不足している場合、プロンプトを表示せず即時に失敗します
--quiet	スピナーと進捗表示を抑制します。標準出力にはデータのみが出力されます
--output json	機械可読な JSON 出力を指定します
--async	タスク ID を即座に返します（動画生成）
--dry-run	実行せずに API リクエストをプレビューします
--yes	確認プロンプトをスキップします

---

コマンド

テキストチャット

チャット補完です。デフォルトモデル：MiniMax-M2.7。

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

フラグ	型	説明
--message <text>	string、必須、繰り返し指定可	メッセージテキストです。role: を先頭に付けるとロールを設定できます（例："system:You are helpful"、"user:Hello"）
--messages-file <path>	string	メッセージ配列を含む JSON ファイルです。標準入力を使用するには - を指定します
--system <text>	string	システムプロンプトです
--model <model>	string	モデル ID（デフォルト：MiniMax-M2.7）
--max-tokens <n>	number	最大トークン数（デフォルト：4096）
--temperature <n>	number	サンプリング温度（0.0、1.0]
--top-p <n>	number	nucleus sampling のしきい値
--stream	boolean	トークンをストリーミングします（TTY ではデフォルトで有効）
--tool <json-or-path>	string、繰り返し指定可	ツール定義の JSON またはファイルパスです

# 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

標準出力：応答テキスト（テキストモード）、または応答オブジェクト全体（JSON モード）。

---

画像生成

画像を生成します。モデル：image-01。

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

フラグ	型	説明
--prompt <text>	string、必須	画像の説明です
--aspect-ratio <ratio>	string	例：16:9、1:1
--n <count>	number	画像の枚数（デフォルト：1）
--subject-ref <params>	string	被写体の参照：type=character,image=path-or-url
--out-dir <dir>	string	画像をダウンロードするディレクトリです
--out-prefix <prefix>	string	ファイル名のプレフィックス（デフォルト：image）

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)

---

動画生成

動画を生成します。デフォルトモデル：MiniMax-Hailuo-2.3。非同期タスクであり、デフォルトでは完了までポーリングします。

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

フラグ	型	説明
--prompt <text>	string、必須	動画の説明です
--model <model>	string	MiniMax-Hailuo-2.3（デフォルト）または MiniMax-Hailuo-2.3-Fast
--first-frame <path-or-url>	string	最初のフレーム画像です
--callback-url <url>	string	完了通知用の Webhook URL です
--download <path>	string	動画を指定したファイルに保存します
--async	boolean	タスク ID を即座に返します
--no-wait	boolean	--async と同じです
--poll-interval <seconds>	number	ポーリング間隔（デフォルト：5）

# 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

動画タスクの取得

動画生成タスクのステータスを照会します。

mmx video task get --task-id <id> [--output json]

動画のダウンロード

タスク ID を指定して、生成が完了した動画をダウンロードします。

mmx video download --file-id <id> [--out <path>]

---

speech synthesize

テキスト読み上げです。デフォルトモデル：speech-2.8-hd。最大 10k 文字です。

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

フラグ	型	説明
--text <text>	string	合成するテキスト
--text-file <path>	string	ファイルからテキストを読み込みます。標準入力には - を使用します
--model <model>	string	speech-2.8-hd（デフォルト）、speech-2.6、speech-02
--voice <id>	string	音声 ID（デフォルト：English_expressive_narrator）
--speed <n>	number	速度の倍率
--volume <n>	number	音量
--pitch <n>	number	ピッチの調整
--format <fmt>	string	音声形式（デフォルト：mp3）
--sample-rate <hz>	number	サンプルレート（デフォルト：32000）
--bitrate <bps>	number	ビットレート（デフォルト：128000）
--channels <n>	number	音声チャンネル数（デフォルト：1）
--language <code>	string	言語ブースト
--subtitles	boolean	字幕のタイミングデータを含めます
--pronunciation <from/to>	string, repeatable	カスタム発音
--sound-effect <effect>	string	効果音を追加します
--out <path>	string	音声をファイルに保存します
--stream	boolean	生の音声を標準出力にストリーミングします

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

音楽を生成します。モデル：music-2.5。詳細で構造化された説明に適しています。

mmx music generate --prompt <text> [--lyrics <text>] [flags]

フラグ	型	説明
--prompt <text>	string	音楽スタイルの説明（詳細に指定できます）
--lyrics <text>	string	構成タグ付きの歌詞。インストゥルメンタルの場合は "\u65e0\u6b4c\u8bcd" を使用します。--instrumental と併用できません
--lyrics-file <path>	string	ファイルから歌詞を読み込みます。標準入力には - を使用します
--vocals <text>	string	ボーカルのスタイル。例："warm male baritone"、"bright female soprano"、"duet with harmonies"
--genre <text>	string	音楽のジャンル。例：フォーク、ポップ、ジャズ
--mood <text>	string	雰囲気や感情。例：温かい、憂うつ、高揚感のある
--instruments <text>	string	フィーチャーする楽器。例："acoustic guitar, piano"
--tempo <text>	string	テンポの説明。例：速い、遅い、中程度
--bpm <number>	number	1 分あたりの拍数で指定する正確なテンポ
--key <text>	string	調。例：ハ長調、イ短調、嬰ト
--avoid <text>	string	生成する音楽で避ける要素
--use-case <text>	string	用途のコンテキスト。例："background music for video"、"theme song"
--structure <text>	string	曲の構成。例："verse-chorus-verse-bridge-chorus"
--references <text>	string	参考にする楽曲やアーティスト。例："similar to Ed Sheeran"
--extra <text>	string	追加の詳細要件
--instrumental	boolean	インストゥルメンタル音楽を生成します（ボーカルなし）。--lyrics または --lyrics-file と併用できません
--aigc-watermark	boolean	AI 生成コンテンツの透かしを埋め込みます
--format <fmt>	string	音声形式（デフォルト：mp3）
--sample-rate <hz>	number	サンプルレート（デフォルト：44100）
--bitrate <bps>	number	ビットレート（デフォルト：256000）
--out <path>	string	音声をファイルに保存します
--stream	boolean	生の音声を標準出力にストリーミングします

--prompt または --lyrics のいずれかが必須です。

# 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

VLM による画像理解です。--image または --file-id のいずれかを指定してください。両方は指定できません。

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

フラグ	型	説明
--image <path-or-url>	string	ローカルパスまたは URL（自動的に base64 エンコードされます）
--file-id <id>	string	アップロード済みファイルの ID（base64 エンコードを省略します）
--prompt <text>	string	画像についての質問（デフォルト："Describe the image."）

mmx vision describe --image photo.jpg --prompt "What breed?" --output json

標準出力：説明テキスト（テキストモード）または完全なレスポンス（JSON モード）。

---

search query

MiniMax によるウェブ検索です。

mmx search query --q <query>

フラグ	型	説明
--q <query>	string, 必須	検索クエリ

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

---

quota show

Token Plan の使用状況と残りのクォータを表示します。

mmx quota show [--output json]

---

ツールスキーマのエクスポート

すべてのコマンドを Anthropic／OpenAI 互換の JSON ツールスキーマとしてエクスポートします。

# All tool-worthy commands (excludes auth/config/update)
mmx config export-schema

# Single command
mmx config export-schema --command "video generate"

これを使うと、エージェントフレームワークで mmx コマンドをツールとして動的に登録できます。

---

終了コード

コード	意味
0	成功
1	一般的なエラー
2	使用方法のエラー（無効なフラグ、不足している引数）
3	認証エラー
4	クォータ超過
5	タイムアウト
10	コンテンツフィルターが作動しました

---

パイプ処理のパターン

# 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

---

設定の優先順位

CLI フラグ → 環境変数 → ~/.mmx/config.json → デフォルト値。

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

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