> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heihuzi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MiniMax 视频：创建任务

> 用 MiniMax-H3-Max 或 MiniMax-H3 异步生成视频，支持文生视频、首帧与尾帧、参考图和参考视频。

`POST https://code.heihuzi.ai/v2/video_generation` 创建一个视频生成任务，请求和返回的字段与 MiniMax 的视频生成接口相同。任务异步执行：创建后返回 `task_id`，再用[查询任务](https://docs.heihuzi.ai/cn/api-reference/videos/minimax-v2/query.md)获取成片链接。

请使用绑定「MiniMax 视频」分组的 API Key。

```bash 文生视频 theme={null}
curl --fail-with-body --silent --show-error \
  --request POST \
  --url https://code.heihuzi.ai/v2/video_generation \
  --header "Authorization: Bearer $HEIHUZI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "MiniMax-H3-Max",
  "content": [
    {"type": "text", "text": "一只橘猫在窗台上伸懒腰，阳光洒进来，镜头缓慢推近"}
  ],
  "resolution": "480P",
  "duration": 5,
  "ratio": "16:9"
}'
```

运行前设置环境变量 `HEIHUZI_API_KEY`。

## 请求参数

**model** `string` *required*

`MiniMax-H3-Max` 或 `MiniMax-H3`。

**content** `object[]` *required*

输入内容数组。必须包含且只包含一项文字，其余各项可选：

* 文字：`{"type": "text", "text": "画面与动作描述"}`
* 首帧图：`{"type": "image_url", "role": "first_frame", "image_url": {"url": "https://example.com/first.jpg"}}`，填 https 图片链接或 Base64 编码，1 张。
* 尾帧图：`{"type": "image_url", "role": "last_frame", "image_url": {"url": "https://example.com/last.jpg"}}`，填 https 图片链接或 Base64 编码，1 张。`MiniMax-H3` 可以只给尾帧；`MiniMax-H3-Max` 给尾帧时必须同时给首帧。
* 参考图：`{"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/reference.jpg"}}`，填 https 图片链接或 Base64 编码，最多 9 张。
* 参考视频：`{"type": "video_url", "role": "reference_video", "video_url": {"url": "https://example.com/reference.mp4"}}`，填 https 视频链接，最多 3 个，合计不超过 15 秒。

首帧图、尾帧图不能和参考图、参考视频同时使用；参考图和参考视频可以一起用。图片和视频的格式、大小等要求见下方「输入素材要求」。

**resolution** `string` *required*

清晰度。`MiniMax-H3-Max`：`480P`、`768P`；`MiniMax-H3`：`768P`、`2K`。

**duration** `integer` *required*

时长（秒）。`MiniMax-H3-Max`：5–15；`MiniMax-H3`：4–15。

**ratio** `string`

画面比例：`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。只有文字时必须填写；带首帧图或尾帧图时由图片决定比例，不需要填写；带参考图或参考视频时可以不填，由模型自动选择。

**extra** `object`

额外生成选项，仅 `MiniMax-H3-Max`。支持 `{"prompt_expansion_mode": "balanced"}`（提示词均衡扩写，不传时也按此处理）。

**aigc\_watermark** `boolean`

传 `true` 时在视频右下角加“AI生成”标识；不传则不加。

## 输入素材要求

请求体不超过 64 MB，大文件请用链接，不要用 Base64 编码。

图片（首帧图、尾帧图、参考图）：

| 项目 | 要求 |
| - | - |
| 格式 | JPG、JPEG、PNG、WEBP、HEIC、HEIF |
| 大小 | 单张不超过 30 MB |
| 宽高 | 每条边 256–5760 像素 |
| 宽高比（宽/高） | 0.4–2.5 |
| 数量 | 首帧图 1 张；尾帧图 1 张；参考图最多 9 张 |

参考视频：

| 项目 | 要求 |
| - | - |
| 格式 | MP4、MOV，链接的路径必须以 `.mp4` 或 `.mov` 结尾 |
| 编码 | 视频 H.264、H.265；音频 AAC、MP3 |
| 大小 | 单个不超过 50 MB |
| 数量 | 最多 3 个 |
| 时长 | 单个 2–15 秒，合计不超过 15 秒 |
| 宽高 | 每条边 256–5760 像素 |
| 宽高比（宽/高） | 0.4–2.5 |
| 帧率 | 23.976–60 |

## 示例

### 首帧图

把本机图片转换为 Base64 字符串，写成 `data:image/jpeg;base64,<Base64 编码>` 填入 `image_url.url`。不要填本机文件路径（如 `/Users/...`、`file://...`）。

```bash theme={null}
IMAGE_BASE64=$(base64 < first.jpg | tr -d '\n')
cat > request.json <<JSON
{
  "model": "MiniMax-H3-Max",
  "content": [
    {"type": "text", "text": "一只手从枝头摘下沾着露水的红苹果，阳光透过树叶，镜头缓慢推近"},
    {"type": "image_url", "role": "first_frame", "image_url": {"url": "data:image/jpeg;base64,${IMAGE_BASE64}"}}
  ],
  "resolution": "480P",
  "duration": 5
}
JSON
curl --fail-with-body --silent --show-error \
  --request POST \
  --url https://code.heihuzi.ai/v2/video_generation \
  --header "Authorization: Bearer $HEIHUZI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data @request.json
```

### 参考图

在文字里说明参考图里的内容怎么用。

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "content": [
    {"type": "text", "text": "参考图里的卡通男孩和柯基小狗一起在草地上奔跑，镜头跟随"},
    {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/boy.png"}},
    {"type": "image_url", "role": "reference_image", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQ..."}}
  ],
  "resolution": "480P",
  "duration": 5,
  "ratio": "16:9"
}
```

### 参考视频

在文字里说明参考视频怎么用。

```json theme={null}
{
  "model": "MiniMax-H3-Max",
  "content": [
    {"type": "text", "text": "沿用参考视频里卡通角色的样子和画风，让它在白色背景前开心地转一圈"},
    {"type": "video_url", "role": "reference_video", "video_url": {"url": "https://example.com/reference.mp4"}}
  ],
  "resolution": "480P",
  "duration": 5,
  "ratio": "16:9"
}
```

## 响应

```json theme={null}
{"task_id":"video_e992bbae16f64f0fa2ef2d18d5a22360"}
```

`task_id` 是任务号，用它[查询](https://docs.heihuzi.ai/cn/api-reference/videos/minimax-v2/query.md)和[删除](https://docs.heihuzi.ai/cn/api-reference/videos/minimax-v2/delete.md)任务。

## 计费

* 按成片秒数计费，不同型号、清晰度单价不同，价格以便利店当前分组配置和用量明细为准。
* 提交时按请求的秒数冻结余额，生成成功后扣除；生成失败或请求被拒绝时全额退回。
* 首帧图、尾帧图不另外收费。
* 参考图：`MiniMax-H3-Max` 的前 2 张、`MiniMax-H3` 的前 5 张不另外收费，超出的按张计费。
* 参考视频：按参考视频的时长另外计费。提交时先按 15 秒冻结，生成成功后按实际时长扣除，多冻结的退回。

## 错误响应

```json theme={null}
{"type":"error","error":{"type":"bad_request_error","code":"invalid_ratio","message":"text-to-video requires ratio, one of 21:9, 16:9, 4:3, 1:1, 3:4, 9:16","http_code":"400"}}
```

| HTTP | `error.code` | 说明 |
| - | - | - |
| 400 | `invalid_model` | `model` 不是支持的型号 |
| 400 | `missing_prompt` | `content` 里没有文字 |
| 400 | `invalid_resolution` | 清晰度不是该型号支持的取值 |
| 400 | `invalid_seconds` | 时长不在该型号支持的范围内 |
| 400 | `invalid_ratio` | 画面比例不支持，或只有文字时没有填写 `ratio` |
| 400 | `invalid_content` | 首帧图或尾帧图和参考图同时使用 |
| 400 | `upstream_error` | 请求被视频服务拒绝，例如 `MiniMax-H3-Max` 只给了尾帧 |
| 400 | `invalid_reference_images` | 参考图超过 9 张 |
| 400 | `invalid_reference_videos` | 参考视频超过 3 个，或和首帧图、尾帧图同时使用 |
| 429 | `too_many_active_tasks` | 未完成的视频任务已有 5 个（MiniMax 和 Seedance 的任务合计），请等前面的完成后再提交 |

参数不符合要求时不会冻结余额。参考视频链接的路径不以 `.mp4` 或 `.mov` 结尾时，请求会被拒绝，冻结的余额全额退回。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.