mmx-h3-video

使用 MMX 生成 MiniMax-H3 视频

本 Skill 仅适用于 MiniMax-H3 视频生成。请勿用于处理文本、图像生成、语音、音乐、搜索、旧版海螺模型或无关的 MMX 命令。

在发起付费请求前，请先阅读 references/h3-video.md，了解提示词构建、媒体限制、等待机制与异常处理。

必选规则

必须使用按量付费（Pay-as-you-go/Credit）API Key。H3 不支持 OAuth 或 Token 套餐订阅 Key。
优先复用已保存的 MMX API Key。切勿在终端日志或命令中明文打印、重复或泄漏 API Key。
必须显式传入 --model MiniMax-H3，绝不要依赖配置中的默认模型。
针对需要直接获取最终视频的场景，请执行一条阻塞式的 mmx video generate 命令。不要使用 Bash 包装脚本或手写轮询循环。
如果终端命令正在运行，请持续等待该执行会话结束。不要运行 ps、抓取进程参数、反复检查输出、强行杀掉进程或提交新任务。
将 Detecting region... cn 或 Detecting region... global 视为正常的 stderr 进度日志，而非提交失败。
切勿因为终端等待、状态轮询或下载中断而重新提交付费任务。
仅当首次命令因 Region 识别、 Endpoint 或鉴权路由在任务创建前明确失败时，才允许重试一次备用 Region。
仅在用户明确需要获取 Task ID 且无需等待或下载时，才使用 --async。

解析 CLI 工具

在 minimax-cli 仓库内部，构建最新代码并使用本地产物：

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

在仓库外部，请直接使用已安装的 mmx 可执行文件。除非用户明确要求，否则不要安装或更新 MMX。

下方的命令中，若在本地仓库构建环境中测试，请将 mmx 替换为 node ./dist/mmx.mjs。

解析与保存 API Key

在发起首次付费 H3 请求前，检查当前生效的凭证（切勿泄露）：

mmx auth status --output json --quiet

如果 method 为 api-key，直接复用 MMX 配置中的凭证。不要在生成命令中附加 --api-key。
如果用户已提供 Key 且运行时已将其安全存在 MINIMAX_API_KEY 环境变量中，保存一次后即可直接使用 MMX 配置：

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

保存 api_key 会替换旧的 OAuth 凭证、清除缓存的 Region，并将 Key 安全保存在仅所有者可读写（owner-only）的 ~/.mmx/config.json 中。
绝不要将之前传入的 Key 拼装为明文 Shell 命令。优先使用运行时的密钥/环境变量注入。
若既无已保存的 API Key 也无安全注入的环境变量，请提示用户运行 mmx auth login 并选择 API key 登录。切勿让用户重新在对话中粘贴 Key。
保存成功后，后续 Agent 命令必须同时省去明文 Key 和 --api-key 参数。

默认生成完整视频路径

当用户希望获取最终视频文件时使用此路径：

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

该单条 CLI 进程会自动提交一次任务、内部定时轮询状态，并在完成后自动下载视频。当执行工具返回正在运行的会话或 Cell ID 时，保持在该会话上等待直至其退出。

不要在此命令中添加 --async。异步模式会在下载处理前提前返回。

输入模式

每次请求仅使用一种输入模式。

文生视频

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

首尾帧视频

--image 代表首帧，可与一个 --last-frame 搭配使用。

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 兼容别名。

多模态参考视频

重复传入参考标记以提供多个输入。切勿使用逗号分隔路径。

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）与参考模式（Reference mode）不能混用。参考音频必须搭配至少一张参考图片或一段参考视频。

Region 容灾恢复

首次请求时省略 --region，让 MMX 自动使用或识别 Key 对应的 Region。若该命令失败，仅当满足以下所有条件时，才允许使用备用 Region 重试一次完全相同的请求：

未返回任何 taskId。
终端未打印 [Model: MiniMax-H3]，即 CLI 未确认任务已创建。
报错信息明确与 Region 识别、区域 Endpoint 或提交前的 401/403 鉴权路由不匹配相关。

在 cn 尝试失败后使用 --region global，或在 global 尝试失败后使用 --region cn。保持所有生成参数不变。若备用 Region 成功，在不暴露凭证的前提下持久化该配置：

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

请勿针对校验错误、2013 报错、欠费/计费问题、速率限制、敏感内容控审、通用服务错误或模糊的超时进行 Region 回退。任务成功创建后、轮询期间或下载期间，绝不要重试 Region。

核心限制

提示词（Prompt）：最多 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 未完全校验的官方时长、编码器、帧率、尺寸及宽高比限制。

异步 Task-ID 路径

仅当用户明确希望立即提交并获取 Task ID 时使用：

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

返回并保存 taskId 后即终止操作。不要自动轮询监控或下载。MMX 不提供任务列表命令，也不会在本地持久化历史任务。

提示词处理

保持用户原意。使用用户的语言编写 Prompt。当 Prompt 过于简短时，可结合以下要素扩展一次：

时长、宽高比与应用场景。
主体及参考映射关系。
按时间顺序排列的动作。
场景、光照、天气与背景。
景别、角度、运镜、焦点与剪辑。
风格、色彩、氛围与节奏。
对白、环境音、音乐及音频同步。
需要保留的元素与需要避免的瑕疵。

对于包含两张及以上有序参考图的情况，使用结构化分镜 Prompt 替代单段散文式文本：

输出规格与有序参考图数量。
全局视觉风格与连贯性规则。
锁定的角色身份、服装、位置与道具。
映射到 reference image 1、reference image 2 等的连续主时间轴。
每个镜头内部的微观时间轴：起势/建立（establish）、预备（prepare）、执行（execute）、落定/保持（settle/hold）与终态锁定（end-state lock）。
用于交接或精准动作交接的明确动作与物体状态转换。
音效要求与最终的负面限制块（negative constraints）。

使用两级时间轴。主时间轴将整个片段划分为若干镜头（shot）。每个镜头再将其自身的时间区间划分为带时间戳的微观拍子（micro-beats）。一个镜头可包含多个阶段，但必须构成一个因果连贯的动作拍。每个镜头必须写明确切的区间范围、时长、参考图、初始状态、镜头运镜、微观拍子与锁定的终态。下一个镜头的初始状态必须等于上一个镜头锁定的终态。

主时间轴与微观时间轴的区间必须完整覆盖父级时长，不得有重叠或空隙，且参考图编号必须与重复传入的 --reference-image 参数顺序一致。确保动作可在 4-15 秒内合理完成。切勿擅自添加品牌、名人、对白、文字叠加或违规不安全内容。使用 references/h3-video.md 中提供的详细中英文模板。

如果用户已提供完整的结构化分镜 Prompt，不要对其进行总结、缩短、翻译或风格化重写。仅检查 7000 字符限制、时长覆盖范围、参考图数量/顺序、媒体模式兼容性以及矛盾的限制条件；除非必须修正错误，否则保留原始表述。