mmx-h3-video

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MiniMax-H3 Video With MMX

使用MMX CLI生成MiniMax-H3视频

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.

本技能仅用于

MiniMax-H3

视频生成，不处理文本、图像生成、语音、音乐、搜索、旧版海洛模型或无关的MMX命令。

发起付费请求前，请阅读

references/h3-video.md

了解提示词构建、媒体约束、等待机制和故障处理相关内容。

Required Rules

必须遵守的规则

Use a Pay-as-you-go/Credit API Key. H3 does not use OAuth or Token Plan Subscription Keys.
Reuse a saved MMX API key when available. Never print, repeat, or place a literal API key in a command transcript.
Always pass
```
--model MiniMax-H3
```
; never rely on the configured default model.
For a completed video, run one direct blocking
```
mmx video generate
```
command. Do not use Bash wrappers or hand-written polling loops.
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.
Treat
```
Detecting region... cn
```
or
```
Detecting region... global
```
as normal stderr progress, not a submission failure.
Never submit a replacement paid task because terminal waiting, status polling, or downloading was interrupted.
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.
Use
```
--async
```
only when the user explicitly wants a task ID without waiting or downloading.

使用按需付费（Pay-as-you-go）/信用额度API密钥。H3不支持OAuth或令牌计划订阅密钥。
若已有保存的MMX API密钥，请重复使用。切勿在命令记录中打印、重复或直接写入明文API密钥。
务必传入
```
--model MiniMax-H3
```
参数；切勿依赖配置的默认模型。
对于已完成的视频，运行一条直接阻塞的
```
mmx video generate
```
命令。不要使用Bash包装器或手写轮询循环。
若终端命令仍在运行，请等待当前执行会话结束。不要运行
```
ps
```
命令、抓取进程参数、反复检查输出、终止进程或提交其他任务。
将
```
Detecting region... cn
```
或
```
Detecting region... global
```
视为正常的stderr进度信息，而非提交失败。
切勿因终端等待、状态轮询或下载中断而提交替代的付费任务。
仅当首次命令因区域检测、端点或认证路由问题在任务创建前明确失败时，最多重试一次切换区域的请求。
仅当用户明确希望获取任务ID而无需等待或下载时，才使用
```
--async
```
参数。

Resolve The CLI

解析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.

在

minimax-cli

仓库内，构建变更并使用本地产物：

bash

bun run build
node ./dist/mmx.mjs video generate --help

在仓库外，使用已安装的

mmx

可执行文件。除非用户要求，否则不要安装或更新MMX。

在以下命令中，测试本地仓库构建时，请将

mmx

替换为

node ./dist/mmx.mjs

。

Resolve And Save The API Key

解析并保存API密钥

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

首次发起付费H3请求前，在不暴露密钥的情况下检查当前凭证：

bash

mmx auth status --output json --quiet

若
```
method
```
为
```
api-key
```
，则从MMX配置中重复使用该密钥。不要在生成命令中添加
```
--api-key
```
参数。
若用户已提供密钥且运行时已将其安全存储为
```
MINIMAX_API_KEY
```
，请保存一次，之后使用MMX配置：

bash

mmx config set --key api_key --value "$MINIMAX_API_KEY" --quiet

保存
```
api_key
```
会替换过期的OAuth凭证、清除缓存的区域，并将密钥存储在
```
~/.mmx/config.json
```
中，仅所有者可访问。
切勿将之前提供的密钥重新构造成可见的Shell文本。若可用，请使用运行时的秘密/环境注入方式。
若无保存的API密钥或安全注入的变量，请要求用户运行
```
mmx auth login
```
并选择API密钥。不要要求他们再次在聊天中粘贴密钥。
保存后，后续Agent命令必须省略明文密钥和
```
--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.

当用户需要最终文件时，使用以下路径：

bash

mmx video generate \
  --model MiniMax-H3 \
  --prompt "<video prompt>" \
  --duration <4-15> \
  --download <output.mp4> \
  --poll-interval 10 \
  --timeout 1800 \
  --non-interactive

该CLI进程仅提交一个任务，在内部等待状态检查间隔，并下载已完成的视频。当执行工具返回运行中的会话或单元ID时，请继续等待该会话直至退出。

不要在此命令中添加

--async

参数。异步模式会在下载处理前返回。

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

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.

--image

为第一帧。可与一个

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

请勿在新命令中使用隐藏的

--first-frame

兼容别名。

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.

重复每个参考标志以传入多个输入。不要用逗号分隔路径。

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

帧模式不能与参考模式混合使用。参考音频要求至少有一个参考图像或参考视频。

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:

No
```
taskId
```
was returned.
```
[Model: MiniMax-H3]
```
was not printed, so the CLI did not confirm task creation.
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

, billing, rate limits, sensitive content, generic service errors, or an ambiguous timeout. Never region-retry after task creation, during polling, or during download.

首次请求时省略

--region

参数，以便MMX使用或检测密钥所属区域。若该命令失败，仅当满足以下所有条件时，才使用备用区域重试一次相同请求：

未返回
```
taskId
```
。
未打印
```
[Model: MiniMax-H3]
```
，即CLI未确认任务创建。
错误明确涉及区域检测、区域端点或提交前的401/403认证路由不匹配。

若

cn

区域尝试失败，则使用

--region global

；若

global

区域尝试失败，则使用

--region cn

。保持所有生成参数不变。若备用区域成功，无需暴露凭证即可持久化设置：

bash

mmx config set --key region --value <global-or-cn> --quiet

对于验证错误、错误

、计费、速率限制、敏感内容、通用服务错误或模糊超时，请勿执行区域回退。任务创建后、轮询期间或下载期间，切勿重试区域切换。

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.

提示词：最多7000字符。
输出时长：4至15秒的整数。
分辨率：2K。
参考图像：最多9张。
参考视频：最多3个。
参考音频：最多3个。
混合参考项：总计最多12个。
本地图像：每张最多30 MB。
本地视频：MP4格式，每个最多50 MB。
本地音频：MP3或WAV格式，每个最多15 MB。
完整本地Base64请求体：最多64 MB。

对于大型或大量资产，请使用URL或

mm_file://<file-id>

。阅读

references/h3-video.md

了解CLI未完全验证的官方时长、编解码器、帧率、尺寸和宽高比限制。

Async Task-ID Path

异步任务ID流程

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.

仅当用户希望立即提交并获取任务ID时使用此流程：

bash

mmx video generate \
  --model MiniMax-H3 \
  --prompt "<video prompt>" \
  --duration <4-15> \
  --async \
  --output json \
  --non-interactive

返回并保留

taskId

，然后停止操作。不要自动监控或下载该任务。MMX不提供任务列表命令，也不会在本地持久化任务历史。

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:

Duration, ratio, and use case.
Subjects and reference mapping.
Chronological actions.
Scene, lighting, weather, and background.
Shot size, angle, camera motion, focus, and cuts.
Style, color, mood, and pacing.
Dialogue, ambience, music, and audio synchronization.
Elements to preserve and artifacts to avoid.

For two or more ordered reference images, use a structured storyboard prompt instead of one prose paragraph:

Output specification and ordered reference count.
Global visual style and continuity rules.
Locked character identity, wardrobe, position, and props.
A contiguous master timeline mapped to
```
reference image 1
```
,
```
reference image 2
```
, and so on.
A micro-timeline inside each shot: establish, prepare, execute, settle/hold, and end-state lock.
Explicit action and object-state transitions for handoffs or other precise motion.
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.

保留用户意图。使用用户的语言编写提示词。当提示词过短时，可通过以下维度扩展一次：

时长、宽高比和使用场景。
主体和参考映射。
时序动作。
场景、光线、天气和背景。
镜头大小、角度、相机运动、焦点和剪辑。
风格、色彩、情绪和节奏。
对话、氛围、音乐和音频同步。
需要保留的元素和需要避免的瑕疵。

对于两张或多张有序参考图像，请使用结构化分镜提示词而非单段散文：

输出规格和有序参考数量。
全局视觉风格和连续性规则。
锁定的角色身份、服装、位置和道具。
映射到
```
reference image 1
```
、
```
reference image 2
```
等的连续主时间线。
每个镜头内的微时间线：建立、准备、执行、稳定/保持和结束状态锁定。
用于切换或其他精确运动的明确动作和对象状态转换。
声音要求和最终的负面约束块。

使用两个时间线层级。主时间线将完整片段划分为多个镜头。每个镜头再将自身区间划分为带时间戳的微节拍。一个镜头可包含多个阶段，但必须形成一个因果动作节拍。每个镜头必须明确说明其精确范围、时长、参考图像、初始状态、相机行为、微节拍和锁定的结束状态。下一个镜头的初始状态必须等于前一个镜头的锁定结束状态。

主时间线和微时间线区间必须覆盖父级时长，无间隙或重叠，且参考编号必须与重复的

--reference-image

标志顺序匹配。确保动作在4-15秒内可完成。请勿悄悄添加品牌、名人、对话、文本叠加层或不安全内容。使用

references/h3-video.md

中的详细中英文模板。

若用户已提供完整的结构化分镜提示词，请勿总结、缩短、翻译或改写风格。仅检查7000字符限制、时长覆盖、参考数量/顺序、媒体模式兼容性和矛盾约束；除非需要修正，否则保留原文措辞。

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.

令牌计划错误/OAuth凭证无效或H3错误
```
2013
```
：停止操作并请求兼容的按需付费API密钥。
明确的提交前区域路由失败：使用备用
```
--region
```
参数重试一次相同命令；任务创建后切勿重试。
认证、余额或敏感内容错误：停止操作并报告确切错误，切勿重试或悄悄修改请求。
终端会话正在运行：继续等待该会话；未返回最终路径不代表失败。
终端任务状态为
```
failed
```
、
```
cancelled
```
或
```
expired
```
：报告状态和任务错误；再次提交付费任务前需获得用户批准。
轮询超时：若有可用的任务ID则报告；请勿提交重复任务。
任务成功后下载失败：仅重试下载相同结果；切勿重新生成视频。

恢复前请阅读

references/h3-video.md

中的完整故障矩阵。