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

# MiniMax-H3

> MiniMax-H3 视频生成：文生视频、首尾帧、多模态参考的参数、示例与计费。

MiniMax 海螺新一代视频模型，支持文生视频、首帧 / 首尾帧图生视频，以及用多张图片、视频、音频作参考的多模态生成，原生同步生成声音。时长 4–15 秒，可选 768P 或 2K。

* 模型 ID：`MiniMax-H3`
* 接口：`POST https://token.poryf.com/v1/videos`（异步任务）
* [查看价格](https://token.poryf.com/pricing/MiniMax-H3) · [在线试用](https://token.poryf.com/model-guide/MiniMax-H3)

## 请求参数

外层只有 `model`、`prompt`、`seconds`；分辨率、比例和参考素材写在 `metadata` 里。

**Authorization** `string` *required*

`Bearer YOUR_API_KEY`，在 [控制台的 API 密钥页](https://token.poryf.com/keys) 创建。

**model** `string` *required*

`MiniMax-H3`

**prompt** `string` *required*

画面、运动与声音描述。有参考素材时也必须填写。

**seconds** `integer` (default: 5)

视频时长：4–15 秒的整数。

**metadata.resolution** `string` (default: 768P)

分辨率：`768P`、`2K`。

**metadata.ratio** `string`

画面比例：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9`、`adaptive`（跟随输入的图片或视频）。不传时，带图片或视频输入为 `adaptive`，纯文字为 `16:9`。`adaptive` 必须配合图片或视频输入。

**metadata.content** `object[]`

参考素材列表，每项形如 `{"type": "image_url", "image_url": {"url": "https://..."}, "role": "reference_image"}`，视频、音频把 `image_url` 换成 `video_url`、`audio_url`。`role` 取值：图片 `first_frame`（首帧）、`last_frame`（尾帧）、`reference_image`（参考图）；视频 `reference_video`；音频 `reference_audio`。图片合计最多 9 张，视频、音频各最多 3 个；首尾帧和参考素材不能混用。

**metadata.aigc\_watermark** `boolean`

是否在视频中加 AI 生成水印。

> [!WARNING]
>
> * 图片、视频、音频请使用公网可访问的 `http(s)` URL，不要上传文件或使用 Base64。
> * 请不要使用 `callback_url` 回调：它不保证可用。请轮询查询任务状态。

## 示例：文生视频

```bash theme={null}
curl https://token.poryf.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "清晨的海边，一只柯基在沙滩上奔跑，镜头缓慢跟随，能听到海浪声",
    "seconds": 5,
    "metadata": {
      "resolution": "768P",
      "ratio": "16:9"
    }
  }'
```

## 示例：首尾帧图生视频

```bash theme={null}
curl https://token.poryf.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "花朵从含苞到完全绽放",
    "seconds": 5,
    "metadata": {
      "content": [
        {"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
        {"type": "image_url", "image_url": {"url": "https://example.com/last.jpg"}, "role": "last_frame"}
      ]
    }
  }'
```

只传 `first_frame` 一张图即为首帧图生视频。

## 示例：多模态参考

用参考图确定人物形象，用参考视频确定动作和运镜：

```bash theme={null}
curl https://token.poryf.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "参考图片中的人物，按照参考视频的动作在城市街头跳舞",
    "seconds": 8,
    "metadata": {
      "resolution": "2K",
      "ratio": "9:16",
      "content": [
        {"type": "image_url", "image_url": {"url": "https://example.com/person.png"}, "role": "reference_image"},
        {"type": "video_url", "video_url": {"url": "https://example.com/dance.mp4"}, "role": "reference_video"}
      ]
    }
  }'
```

## 响应

提交成功后返回任务对象（示例结构）：

```json theme={null}
{
  "id": "task_xxxxxxxx",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "queued",
  "progress": 0
}
```

查询进度、下载视频的方法见 [视频通用说明](https://docs.token.poryf.com/api/videos/overview.md#查询进度)。

## 计费

按秒计费，单价按分辨率（768P / 2K）分两档。实时单价见 [模型广场](https://token.poryf.com/pricing/MiniMax-H3)。

* 生成视频：按输出时长计费。
* 参考视频：按参考视频时长计费，单价与所选分辨率的生成单价相同。
* 图片（首尾帧、参考图）：每个任务前 5 张免费，超出部分按张计费。
* 参考音频、声音生成：免费。

提交时先预扣：时长按请求的 `seconds`（不传按 5 秒）；带参考视频时，参考视频按最长 15 秒预扣。任务完成后按实际时长和图片数多退少补；任务失败自动全额退回。

## 常见错误

| 出现时机 | 错误 | 原因 |
| - | - | - |
| 提交时返回错误 | `MiniMax-H3 duration must be an integer between 4 and 15 seconds` | `seconds` 不是 4–15 之间的整数 |
| 提交时返回错误 | `MiniMax-H3 resolution must be 768P or 2K` | 分辨率写成了其他档位 |
| 提交时返回错误 | `MiniMax-H3 ratio adaptive requires an image or video input` | 纯文字请求传了 `adaptive`，改为具体比例或去掉 `ratio` |
| 提交时返回错误 | `MiniMax-H3 cannot mix frame images with reference media` | 首尾帧和参考图 / 参考视频 / 参考音频放在了同一个请求里 |
| 提交时返回错误 | `MiniMax-H3 accepts at most 9 input images` 等 | 参考素材数量超出上限 |

其他错误见 [排错指南](https://docs.token.poryf.com/errors.md)。


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