Merge pull request #212 from MiniMax-AI/agent/add-hailuo-h3-video-v2

Add Hailuo H3 video generation support

Author: RyanLee-Dev

README.md

@@ -85,12 +85,24 @@ mmx image generate --prompt "Logo" --out-dir ./out/
 ### `mmx video`
 
 ```bash
+# Hailuo-2.3 (Video Generation V1)
 mmx video generate --prompt "Ocean waves at sunset" --download sunset.mp4
 mmx video generate --prompt "A robot painting" --async
+
+# MiniMax-H3 (Video Generation V2)
+mmx video generate --api-key "$MINIMAX_API_KEY" --model MiniMax-H3 --prompt "Ocean waves at sunset"
+mmx video generate --api-key "$MINIMAX_API_KEY" --model MiniMax-H3 --prompt "The subject walks forward" --image start.jpg
+mmx video generate --api-key "$MINIMAX_API_KEY" --model MiniMax-H3 --prompt "Keep the same character" --reference-image character.png --reference-video motion.mp4
+
 mmx video task get --task-id 123456
+mmx video task get --task-id 424010985738629 --model MiniMax-H3
 mmx video download --file-id 176844028768320 --out video.mp4
 ```
 
+For MiniMax-H3, local files and Base64 data URIs are preflight-checked against the documented limits: image 30 MB, reference video 50 MB, reference audio 15 MB, and total JSON request body 64 MB. The API validates dimensions, aspect ratio, duration, frame rate, and codecs for all media.
+
+`--region` is an existing global CLI option, not an H3 parameter. Normal video generation does not need it; the CLI uses the saved or automatically detected region. H3 defaults to 2K, 5 seconds, and 16:9 for text-to-video.
+
 ### `mmx speech`
 
 ```bash

README_CN.md

@@ -85,12 +85,24 @@ mmx image generate --prompt "山水画" --out-dir ./output/
 ### `mmx video`
 
 ```bash
+# Hailuo-2.3（视频生成 V1）
 mmx video generate --prompt "海浪拍打礁石" --download sunset.mp4
 mmx video generate --prompt "机器人作画" --async
+
+# MiniMax-H3（视频生成 V2）
+mmx video generate --api-key "$MINIMAX_API_KEY" --model MiniMax-H3 --prompt "夕阳下的海浪"
+mmx video generate --api-key "$MINIMAX_API_KEY" --model MiniMax-H3 --prompt "主体向前行走" --image start.jpg
+mmx video generate --api-key "$MINIMAX_API_KEY" --model MiniMax-H3 --prompt "保持相同角色和动作" --reference-image character.png --reference-video motion.mp4
+
 mmx video task get --task-id 123456
+mmx video task get --task-id 424010985738629 --model MiniMax-H3
 mmx video download --file-id 176844028768320 --out video.mp4
 ```
 
+MiniMax-H3 会在发送前检查本地文件和 Base64 数据：图片不超过 30 MB、参考视频不超过 50 MB、参考音频不超过 15 MB、JSON 请求体总计不超过 64 MB。所有素材的尺寸、宽高比、时长、帧率和编码格式仍由 API 服务端校验。
+
+`--region` 是 CLI 原有的全局选项，不是 H3 参数。正常生成视频无需填写，CLI 会使用已保存或自动识别的区域。H3 默认使用 2K、5 秒，文生视频默认比例为 16:9。
+
 ### `mmx speech`
 
 ```bash

SDK.md

@@ -65,12 +65,29 @@ const video = await sdk.video.generate({
   prompt: 'Ocean waves at sunset',
 });
 
+// MiniMax-H3 — Video Generation V2 with request defaults
+const h3Video = await sdk.video.generate({
+  model: 'MiniMax-H3',
+  prompt: 'Ocean waves at sunset',
+});
+
 // Asynchronous — returns task ID immediately
 const { taskId } = await sdk.video.generate({
   prompt: 'A robot painting',
   async: true,
 });
 
+const { taskId: h3TaskId } = await sdk.video.generate({
+  model: 'MiniMax-H3',
+  prompt: 'Ocean waves at sunset',
+  async: true,
+});
+
+const h3Task = await sdk.video.getTask({
+  taskId: h3TaskId,
+  model: 'MiniMax-H3',
+});
+
 const task = await sdk.video.getTask({ taskId });
 
 // Download

skill/SKILL.md

@@ -117,7 +117,7 @@ mmx image generate --prompt "Logo" --n 3 --out-dir ./gen/ --quiet
 
 ### video generate
 
-Generate video. Default model: `MiniMax-Hailuo-2.3`. This is an async task — by default it polls until completion.
+Generate video. Default model: `MiniMax-Hailuo-2.3`. Select `MiniMax-H3` to use the Video Generation V2 multimodal API. This is an async task — by default it polls until completion.
 
 ```bash
 mmx video generate --prompt <text> [flags]
@@ -126,8 +126,14 @@ 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` |
-| `--first-frame <path-or-url>` | string | First frame image |
+| `--model <model>` | string | `MiniMax-Hailuo-2.3` (default), `MiniMax-Hailuo-2.3-Fast`, or `MiniMax-H3` |
+| `--image <path-or-url>` | string | Input image for image-to-video |
+| `--last-frame <path-or-url>` | string | Last frame image; H3 supports last-frame-only input |
+| `--reference-image <path-or-url>` | string, repeatable | H3 reference image |
+| `--reference-video <path-or-url>` | string, repeatable | H3 reference video |
+| `--reference-audio <path-or-url>` | string, repeatable | H3 reference audio; requires a reference image or video |
+| `--duration <seconds>` | number | H3 duration, 4-15 seconds (default: 5) |
+| `--ratio <ratio>` | string | H3 output ratio; T2V cannot use `adaptive` |
 | `--callback-url <url>` | string | Webhook URL for completion |
 | `--download <path>` | string | Save video to specific file |
 | `--async` | boolean | Return task ID immediately |
@@ -139,6 +145,18 @@ mmx video generate --prompt <text> [flags]
 mmx video generate --prompt "A robot." --async --quiet
 # stdout: {"taskId":"..."}
 
+# H3 text-to-video
+mmx video generate --model MiniMax-H3 --prompt "Ocean waves." --async --quiet
+
+# H3 image-to-video
+mmx video generate --model MiniMax-H3 --prompt "The subject walks forward." \
+  --image start.jpg --async --quiet
+
+# H3 reference-to-video
+mmx video generate --model MiniMax-H3 --prompt "Keep the same character." \
+  --reference-image character.png \
+  --reference-video motion.mp4 --async --quiet
+
 # Blocking: wait and get file path
 mmx video generate --prompt "Ocean waves." --download ocean.mp4 --quiet
 # stdout: ocean.mp4

src/client/endpoints.ts

@@ -18,10 +18,18 @@ export function videoGenerateEndpoint(baseUrl: string): string {
   return `${baseUrl}/v1/video_generation`;
 }
 
+export function videoGenerateV2Endpoint(baseUrl: string): string {
+  return `${baseUrl}/v2/video_generation`;
+}
+
 export function videoTaskEndpoint(baseUrl: string, taskId: string): string {
   return `${baseUrl}/v1/query/video_generation?task_id=${taskId}`;
 }
 
+export function videoTaskV2Endpoint(baseUrl: string, taskId: string): string {
+  return `${baseUrl}/v2/query/video_generation/${taskId}`;
+}
+
 export function fileRetrieveEndpoint(baseUrl: string, fileId: string): string {
   return `${baseUrl}/v1/files/retrieve?file_id=${fileId}`;
 }

src/command.ts

@@ -6,6 +6,7 @@ export interface OptionDef {
   description: string;
   type?: 'string' | 'number' | 'boolean' | 'array';
   required?: boolean;
+  hidden?: boolean;
 }
 
 export interface Command {