h3-video/references/h3-video.md
# MiniMax-H3 Video Agent Guide
Read this reference before submitting a `MiniMax-H3` request. It covers rules that are not fully exposed by CLI flags.
## Credential Rule
- Use a standard Pay-as-you-go/Credit API Key for H3.
- Do not use an OAuth credential or Token Plan Subscription Key for H3.
- Run `mmx auth status --output json --quiet` before the first paid request. It reports the credential method and only a masked key.
- Prefer an API key already saved in MMX config. Generation commands should not contain `--api-key`.
- If the runtime securely holds a previously supplied key as `MINIMAX_API_KEY`, save it once with `mmx config set --key api_key --value "$MINIMAX_API_KEY" --quiet`.
- Never print, repeat, or reconstruct a literal key in shell text. If secure injection is unavailable, ask the user to run interactive `mmx auth login` instead of pasting the key into chat again.
- MMX stores config with owner-only permissions. Saving `api_key` removes stale OAuth credentials and clears the cached region for fresh detection.
- If error `2013` says TokenPlan or Credit does not support H3, stop. Select a compatible Pay-as-you-go API Key instead of changing the prompt or media.
## Region Selection And Fallback
- Omit `--region` initially. MMX uses the saved region or detects it after a new API key is saved.
- `Detecting region... cn` and `Detecting region... global` are normal progress messages.
- Retry the alternate region at most once only when the command clearly failed before task creation because of region detection, a regional endpoint, or a pre-submission 401/403 routing mismatch.
- Absence of both a `taskId` and `[Model: MiniMax-H3]` is required before retrying creation. If either appeared, assume a paid task may exist and do not resubmit.
- Keep the request identical and add only `--region global` after `cn`, or `--region cn` after `global`.
- After a successful alternate-region request, persist it with `mmx config set --key region --value <global-or-cn> --quiet`.
- Do not region-retry validation, `2013`, balance, rate-limit, sensitive-content, generic 5xx, terminal task failure, polling, download, or ambiguous timeout errors.
## Waiting And Progress
- The API does not publish a fixed completion ETA or progress percentage for each video.
- Total time varies with queue load, requested duration, and reference-media complexity. Never promise that a task will finish in a specific number of minutes.
- Poll no more frequently than once every 10 seconds.
- Valid lifecycle statuses include `queued`, `running`, `succeeded`, `failed`, `cancelled`, and `expired`.
- For a completed file, use one blocking `mmx video generate` command with `--download`, `--poll-interval 10`, and `--timeout 1800`. The CLI performs status polling internally.
- If the terminal command remains active, wait on the same execution session. Do not start another command or infer failure from missing output while it is still running.
- After 30 minutes, the CLI timeout may stop local polling. Preserve and report `taskId` when available; do not submit a duplicate task automatically.
- MMX has no task-list command and does not persist local task history. Retain the returned task ID.
## Prompt Construction
Preserve the user's intent. When the prompt is underspecified, expand it into one production-oriented prompt in this order:
1. Output goal: duration, aspect ratio, use case, and whether the clip should feel continuous or edited.
2. Subjects and assets: identify people, products, locations, and how each reference image/video/audio should be used.
3. Timeline: describe actions in chronological order with clear transitions.
4. Scene: environment, time of day, lighting, weather, and important background details.
5. Camera: shot size, angle, movement, focus behavior, and cuts.
6. Look: visual style, color, texture, mood, and pacing.
7. Sound: dialogue, ambience, music, sound effects, and synchronization to reference audio.
8. Constraints: elements to preserve and artifacts to avoid, such as identity drift, flicker, text, logos, or abrupt cuts.
When the user already supplies a complete structured storyboard, keep it intact. Do not condense, translate, or replace it with a generic prompt. Only check prompt length, timestamp coverage, reference numbering, media compatibility, and direct contradictions before submission.
Operational heuristics for better results:
- Keep actions physically achievable within the selected 4-15 second duration.
- Prefer one clear action beat per shot instead of packing unrelated events into one block.
- For multiple references, describe them in the same order as the repeated CLI flags: `reference image 1`, `reference image 2`, and so on.
- Make timestamp ranges contiguous, with no gaps or overlaps, and make their final end time equal the requested duration.
- Use a two-level timeline: a master shot range for every reference image, then micro-ranges inside that shot for preparation, execution, settling, and the final hold.
- Use 0.5-second precision by default. Use finer timing only when a short, precise physical transition needs it.
- Every shot must declare: exact range and duration, reference image number, initial state, shot/camera, micro-timeline, and locked end state.
- The locked end state of shot N must be the initial state of shot N+1. Check character pose, gaze, occupied hand, prop owner/location, prop connections, and camera side.
- State what must remain consistent and what may change. Example: preserve face, clothing, and product shape; change pose, camera angle, and background motion.
- Lock persistent spatial relationships explicitly when important: left/right seat, foreground/background, screen direction, and which hand holds an object.
- For handoffs and precise object motion, describe state transitions in causal order: initial owner and location, release condition, transfer, new owner, and final state. Do not compress these into one vague action.
- Separate hard continuity constraints from aesthetic preferences and negative constraints. Repeat a critical invariant in the relevant timeline block when its failure would break the scene.
- Use explicit camera language such as static shot, close-up, tracking shot, dolly in, pan, tilt, handheld, or aerial view.
- Specify audio timing only when audio is supplied. State whether motion, cuts, lip movement, or effects should follow the beat or spoken words.
- Do not silently add brands, dialogue, text overlays, or unsafe content that the user did not request.
Timeline planning procedure:
1. Read total duration `D` and ordered storyboard count `N`.
2. Preserve user-supplied timestamps. Otherwise start with `D / N` seconds per storyboard; for example, 15 seconds with 6 images starts as six 2.5-second shots.
3. Reallocate time by action complexity while keeping all ranges contiguous and totaling exactly `D`. Give precise handoffs or multi-stage physical actions more time; give static establishing or reaction shots less.
4. Split each shot into 3-5 readable micro-beats: establish/hold, preparation, core action, settle/recovery, and optional final hold.
5. Maintain a state ledger at every boundary: character position and pose, gaze, left/right hand state, prop owner and location, physical connections, and camera side.
6. Verify that every reference is used exactly once in input order unless the user explicitly requests reuse, and that shot N's locked end state exactly matches shot N+1's initial state.
7. If the requested actions cannot fit without becoming rushed or ambiguous, simplify the action plan or tell the user before making a paid request. Do not silently compress causal steps.
For two or more ordered storyboard images, use the following structure. Do not flatten it into a single paragraph.
English structured storyboard template:
```text
[OUTPUT SPECIFICATION]
Create a {duration}-second, {ratio} {use case} video using {N} storyboard reference images in their exact input order as consecutive shot references. Follow the timeline without skipping shots or changing locked characters, wardrobe, positions, or key props.
[OVERALL LOOK]
{Live action/animation/product medium}; {cinematic or visual style}; {lighting, color, texture, depth of field, pacing, and camera baseline}. Scene: {environment, time, weather, and background motion}. Sound: {dialogue, ambience, music, reference-audio synchronization, or silence}.
[CHARACTER AND SPATIAL CONTINUITY]
Character 1: {appearance, wardrobe, demeanor}; always at {fixed position}.
Character 2: {appearance, wardrobe, demeanor}; always at {fixed position}.
Preserve {faces, hair, wardrobe, seats, screen direction, proportions, and scene layout} throughout.
[PROP STATE CONTINUITY]
The entire video contains exactly {prop count and names}. Initial state: {owner, hand, location, and connection}. Preserve {shape, count, connection, visibility, and physical behavior}; never duplicate, remove, teleport, disconnect, or silently change ownership.
[TWO-LEVEL TIMELINE AND REFERENCE MAPPING]
Shot 1 | 0:00-{T1} | Duration {D1}s | Reference image 1
Shot and camera: {framing, angle, movement, and focus}.
Initial state: {poses, gazes, both-hand states, prop owner/location/connections}.
In-shot micro-timeline:
- 0:00-{t1a}: Establish the frame with {visible state and subtle environment motion}.
- {t1a}-{t1b}: Preparation: {gaze, weight, hand, or prop begins to change}.
- {t1b}-{t1c}: Core action: {perform only this shot's main action}.
- {t1c}-{T1}: Settle and hold the completed action; do not begin the next shot's action early.
Locked end state: {explicit character, hand, prop, and connection state inherited by shot 2}.
Shot 2 | {T1}-{T2} | Duration {D2}s | Reference image 2
Shot and camera: {framing, angle, movement, and focus}.
Initial state: exactly match shot 1's locked end state.
In-shot micro-timeline:
- {T1}-{t2a}: Hold the inherited state long enough to remain readable.
- {t2a}-{t2b}: {preparation}.
- {t2b}-{t2c}: {core action}.
- {t2c}-{T2}: {completion, recovery, or hold}.
Locked end state: {explicit state}.
{Continue with one complete shot block per reference image. Both the master timeline and every in-shot micro-timeline must be contiguous; the final timestamp must equal duration.}
[STRICT ACTION ORDER]
{Action A} -> {Action B} -> {Action C} -> {Action D}. Do not merge, reorder, or omit steps. Each shot completes one clear action. For a handoff, state who remains still, who establishes and secures contact, and only then when the original holder releases.
[NEGATIVE CONSTRAINTS]
No {unwanted visual genre, editing style, or performance}. No {subtitles, watermarks, extra people, or extra props}. Avoid {identity drift, wardrobe changes, position swaps, flicker, malformed fingers, extra limbs, prop teleportation, broken connections, and abrupt cuts}.
```
For a single text-to-video request or one loose reference, a concise paragraph is acceptable. Use the full storyboard structure when continuity, multiple ordered images, or precise physical interactions matter.
### Detailed Timing Example: Earbud Removal And Handoff
English:
```text
Shot 2 | 0:02.5-0:05.0 | Duration 2.5s | Reference image 2
Initial state: the girl looks at her phone with both earbuds in her ears; she holds the phone; the boy still holds his bag with both hands.
0:02.5-0:03.0: The girl lowers the phone slightly and briefly looks at the boy; all other states remain unchanged.
0:03.0-0:04.1: With the hand closer to the boy, she pinches one earbud stem between thumb and index finger and slowly removes it from her ear.
0:04.1-0:05.0: She holds the earbud at chest height between them; the boy has not reached for it; a visible gap remains between the earbud and his face and ear.
Locked end state: the girl still holds the earbud stem; the other earbud remains in her ear; the cable remains connected to her phone; both of the boy's hands remain on his bag.
Shot 3 | 0:05.0-0:07.5 | Duration 2.5s | Reference image 3
Initial state: exactly inherit shot 2's locked end state.
0:05.0-0:05.5: The girl keeps her hand and the earbud still; the boy pauses.
0:05.5-0:06.4: The boy raises the hand closer to the girl and approaches the earbud stem with thumb and index finger; she does not release it.
0:06.4-0:07.0: The boy grips and secures the earbud stem; only after his grip is stable does the girl release it.
0:07.0-0:07.5: The girl withdraws her hand; the boy holds the earbud but does not move it toward his ear yet.
Locked end state: ownership has transferred to the boy; the earbud remains between them; the girl's hand has left the handoff area; the cable still connects naturally to the girl's phone.
```
## Media Preflight
Frame mode and reference mode cannot be mixed. Reference audio requires at least one reference image or reference video.
| Input | Official count/technical limits | Current local CLI handling |
|---|---|---|
| First frame | At most 1 image | `--image`; at most 30 MB |
| Last frame | At most 1 image | `--last-frame`; at most 30 MB |
| Reference image | At most 9; JPEG/JPG/PNG/WebP; 256-5760 px sides; aspect ratio 0.4-2.5 | JPG/JPEG/PNG/WebP/HEIC/HEIF; at most 30 MB each |
| Reference video | At most 3; MP4/MOV; H.264/H.265; 23.976-60 FPS; each 2-15 seconds; total at most 15 seconds | Local MP4 only; at most 50 MB each. Use URL or `mm_file://` for other supported API inputs |
| Reference audio | At most 3; MP3/WAV; each 2-15 seconds; total at most 15 seconds | Local MP3/WAV; at most 15 MB each |
The total number of reference images, videos, and audios in a mixed-reference request must not exceed 12. Local media is Base64-encoded, and MMX limits the complete request body to 64 MB. Use public URLs or `mm_file://<file-id>` for large or numerous media inputs.
Before a paid request, inspect local video/audio duration and codec once when they are unknown. Do not transcode media unless it violates an actual format or duration rule.
## Failure Handling
Use the shortest non-duplicating response:
| Failure | Action |
|---|---|
| Region detection/endpoint or pre-submission 401/403, with no `taskId` and no model marker | Retry the unchanged request once with the alternate `--region`; if it succeeds, save that region |
| No `taskId` and validation/HTTP 400 | Correct the reported field once; do not alter unrelated parameters |
| `2013` mentioning TokenPlan/Credit and H3 | Stop and use a compatible Pay-as-you-go API Key |
| Authentication error (`1004`, `2049`, HTTP 401/403) | Stop and request a valid key; do not retry |
| Insufficient balance (`1008`, HTTP 402) | Stop and report the billing problem |
| Rate limit (`1002`, HTTP 429) | Wait 60 seconds using the agent runtime's wait capability, then retry the same safe query once. Retry creation only when the response clearly confirms no task was created |
| Sensitive prompt/media (`1026`, `1027`, HTTP 422) | Report the rejected input and ask the user to revise it; do not silently rewrite |
| Temporary service/query error (`1000`, `1001`, `1024`, `1033`, HTTP 5xx) | For an existing task, wait 10 seconds using the agent runtime's wait capability and retry the same status query up to 3 times. Do not submit a replacement task automatically |
| Terminal `failed`, `cancelled`, or `expired` | Report `taskId`, status, and task error; require user approval before creating another paid task |
| Polling exceeds 30 minutes | Let the direct CLI command return its timeout, preserve `taskId` when available, and report that the task may still complete later |
| Download fails after `succeeded` | Retry the same result URL up to 3 times; never regenerate the video |
Once a task ID exists, all recovery must operate on that task ID. Never create a second paid task merely because terminal-session handling, polling, or downloading failed.
h3-video/SKILL.md
---
name: mmx-h3-video
description: Generate, monitor, and download MiniMax-H3 videos through the mmx CLI. Use for H3 text-to-video, first/last-frame video, multimodal reference image/video/audio generation, H3 prompt improvement, media preflight, Pay-as-you-go API key selection, task waiting, downloads, and H3 failure handling.
---
# MiniMax-H3 Video With MMX
Use this skill only for `MiniMax-H3` video generation. Do not handle text, image generation, speech, music, search, legacy Hailuo models, or unrelated MMX commands.
Before a paid request, read `references/h3-video.md` for prompt construction, media constraints, waiting behavior, and failure handling.
## Required Rules
1. Use a Pay-as-you-go/Credit API Key. H3 does not use OAuth or Token Plan Subscription Keys.
2. Reuse a saved MMX API key when available. Never print, repeat, or place a literal API key in a command transcript.
3. Always pass `--model MiniMax-H3`; never rely on the configured default model.
4. For a completed video, run one direct blocking `mmx video generate` command. Do not use Bash wrappers or hand-written polling loops.
5. If the terminal command remains active, wait on that exact execution session. Do not run `ps`, scrape process arguments, inspect the output repeatedly, kill the process, or submit another task.
6. Treat `Detecting region... cn` or `Detecting region... global` as normal stderr progress, not a submission failure.
7. Never submit a replacement paid task because terminal waiting, status polling, or downloading was interrupted.
8. Retry the alternate region at most once, and only when the first command clearly failed before task creation because of region detection, endpoint, or authentication routing.
9. Use `--async` only when the user explicitly wants a task ID without waiting or downloading.
## Resolve The CLI
Inside the `minimax-cli` repository, build changes and use the local artifact:
```bash
bun run build
node ./dist/mmx.mjs video generate --help
```
Outside the repository, use the installed `mmx` executable. Do not install or update MMX unless the user asks.
In commands below, replace `mmx` with `node ./dist/mmx.mjs` when testing the local repository build.
## Resolve And Save The API Key
Before the first paid H3 request, inspect the active credential without exposing it:
```bash
mmx auth status --output json --quiet
```
- If `method` is `api-key`, reuse it from MMX config. Do not add `--api-key` to generation commands.
- If the user already supplied a key and the runtime holds it securely as `MINIMAX_API_KEY`, save it once, then use MMX config:
```bash
mmx config set --key api_key --value "$MINIMAX_API_KEY" --quiet
```
- Saving `api_key` replaces stale OAuth credentials, clears the cached region, and stores the key in `~/.mmx/config.json` with owner-only permissions.
- Never reconstruct a previously supplied key into visible shell text. Use the runtime's secret/environment injection when available.
- If no saved API key or securely injected variable is available, ask the user to run `mmx auth login` and choose API key. Do not ask them to paste the key into chat again.
- After saving, future Agent commands must omit both the literal key and `--api-key`.
## Default Completed-Video Path
Use this path when the user wants the final file:
```bash
mmx video generate \
--model MiniMax-H3 \
--prompt "<video prompt>" \
--duration <4-15> \
--download <output.mp4> \
--poll-interval 10 \
--timeout 1800 \
--non-interactive
```
This one CLI process submits exactly one task, waits internally between status checks, and downloads the completed video. When the execution tool returns a running session or cell ID, continue waiting on that same session until it exits.
Do not add `--async` to this command. Async mode returns before download handling.
## Input Modes
Use exactly one mode per request.
### Text-To-Video
```bash
mmx video generate \
--model MiniMax-H3 \
--prompt "A cinematic coastal sunset, slow dolly forward" \
--duration 15 \
--ratio 16:9 \
--download ./result.mp4 \
--poll-interval 10 \
--timeout 1800 \
--non-interactive
```
### First/Last-Frame Video
`--image` is the first frame. It may be combined with one `--last-frame`.
```bash
mmx video generate \
--model MiniMax-H3 \
--prompt "The subject walks naturally from the starting pose to the ending pose" \
--image ./start.png \
--last-frame ./end.png \
--duration 15 \
--download ./result.mp4 \
--poll-interval 10 \
--timeout 1800 \
--non-interactive
```
Do not use the hidden `--first-frame` compatibility alias in new commands.
### Multimodal Reference Video
Repeat each reference flag to pass multiple inputs. Do not comma-separate paths.
```bash
mmx video generate \
--model MiniMax-H3 \
--prompt "Preserve the referenced character, follow the motion and audio rhythm" \
--reference-image ./character-1.png \
--reference-image ./character-2.png \
--reference-video ./motion.mp4 \
--reference-audio ./rhythm.mp3 \
--duration 15 \
--download ./result.mp4 \
--poll-interval 10 \
--timeout 1800 \
--non-interactive
```
Frame mode cannot be mixed with reference mode. Reference audio requires at least one reference image or reference video.
## Region Recovery
Omit `--region` on the first request so MMX can use or detect the key's region. If that command fails, retry the same request once with the alternate region only when all of these are true:
1. No `taskId` was returned.
2. `[Model: MiniMax-H3]` was not printed, so the CLI did not confirm task creation.
3. The error explicitly concerns region detection, a regional endpoint, or a pre-submission 401/403 authentication-routing mismatch.
Use `--region global` after a failed `cn` attempt, or `--region cn` after a failed `global` attempt. Keep every generation argument unchanged. If the alternate region succeeds, persist it without exposing credentials:
```bash
mmx config set --key region --value <global-or-cn> --quiet
```
Do not perform region fallback for validation errors, error `2013`, billing, rate limits, sensitive content, generic service errors, or an ambiguous timeout. Never region-retry after task creation, during polling, or during download.
## Core Limits
- Prompt: at most 7000 characters.
- Output duration: integer from 4 through 15 seconds.
- Resolution: 2K.
- Reference images: at most 9.
- Reference videos: at most 3.
- Reference audios: at most 3.
- Mixed reference items: at most 12 total.
- Local image: at most 30 MB each.
- Local video: MP4, at most 50 MB each.
- Local audio: MP3 or WAV, at most 15 MB each.
- Complete local Base64 request body: at most 64 MB.
Use URLs or `mm_file://<file-id>` for large or numerous assets. Read `references/h3-video.md` for official duration, codec, frame-rate, dimension, and aspect-ratio limits that are not fully validated by the CLI.
## Async Task-ID Path
Use this only when the user wants immediate submission and a task ID:
```bash
mmx video generate \
--model MiniMax-H3 \
--prompt "<video prompt>" \
--duration <4-15> \
--async \
--output json \
--non-interactive
```
Return and retain the `taskId`, then stop. Do not automatically monitor or download it. MMX does not provide a task-list command or persist local task history.
## Prompt Handling
Preserve the user's intent. Write the prompt in the user's language. When a prompt is too short, expand it once using:
1. Duration, ratio, and use case.
2. Subjects and reference mapping.
3. Chronological actions.
4. Scene, lighting, weather, and background.
5. Shot size, angle, camera motion, focus, and cuts.
6. Style, color, mood, and pacing.
7. Dialogue, ambience, music, and audio synchronization.
8. Elements to preserve and artifacts to avoid.
For two or more ordered reference images, use a structured storyboard prompt instead of one prose paragraph:
1. Output specification and ordered reference count.
2. Global visual style and continuity rules.
3. Locked character identity, wardrobe, position, and props.
4. A contiguous master timeline mapped to `reference image 1`, `reference image 2`, and so on.
5. A micro-timeline inside each shot: establish, prepare, execute, settle/hold, and end-state lock.
6. Explicit action and object-state transitions for handoffs or other precise motion.
7. Sound requirements and a final negative-constraint block.
Use two timeline levels. The master timeline divides the full clip into shots. Each shot then divides its own interval into timestamped micro-beats. A shot may contain several phases, but they must form one causal action beat. Every shot must state its exact range, duration, reference image, initial state, camera behavior, micro-beats, and locked end state. The next shot's initial state must equal the previous locked end state.
Master and micro intervals must cover their parent duration without gaps or overlaps, and reference numbering must match the repeated `--reference-image` flag order. Keep the action achievable within 4-15 seconds. Do not silently add brands, celebrities, dialogue, text overlays, or unsafe content. Use the detailed Chinese and English templates in `references/h3-video.md`.
If the user already provides a complete structured storyboard prompt, do not summarize, shorten, translate, or stylistically rewrite it. Check only the 7000-character limit, duration coverage, reference count/order, media-mode compatibility, and contradictory constraints; preserve the original wording unless a correction is required.
## Failure Handling
- Wrong Token Plan/OAuth credential or H3 error `2013`: stop and request a compatible Pay-as-you-go API Key.
- Clear pre-submission region-routing failure: retry the unchanged command once with the alternate `--region`; never retry after task creation.
- Authentication, balance, or sensitive-content errors: stop and report the exact error without retrying or silently changing the request.
- A running terminal session: keep waiting on the same session; absence of a final path is not failure.
- Terminal task status `failed`, `cancelled`, or `expired`: report the status and task error; require approval before another paid submission.
- Polling timeout: report the task ID when available; do not submit a duplicate.
- Download failure after success: retry the same result download only; never regenerate the video.
Read the complete failure matrix in `references/h3-video.md` before recovery.
SKILL.md
---
name: mmx-cli
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
```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.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).
```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.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 |
```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
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>
```
| Flag | Type | Description |
|---|---|---|
| `--q <query>` | string, **required** | Search query |
```bash
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
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Usage error (bad flags, missing args) |
| 3 | Authentication error |
| 4 | Quota exceeded |
| 5 | Timeout |
| 10 | Content 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
```
### Default Model Configuration
Set per-modality defaults so you don't need `--model` every time:
```bash
# Set defaults
mmx config set --key default-text-model --value MiniMax-M3.1-Flash
mmx config set --key default-speech-model --value speech-2.8-hd
mmx config set --key default-video-model --value MiniMax-Hailuo-2.3
# Use without --model
mmx text chat --message "Hello"
mmx speech synthesize --text "Hello" --out hello.mp3
mmx video generate --prompt "Ocean waves"
# --model still overrides per-call
mmx text chat --model MiniMax-M3.1-Flash --message "Hello"
```
**Resolution priority**: `--model` flag > config default > hardcoded fallback.