# MiniMax H3 / H3 Max

> 使用 MiniMax 原生 JSON 接口创建 H3 与 H3 Max 视频任务，并查询任务、输入素材、处理 Context、再生成和管理任务。

Canonical URL: https://docs.uniai.tv/models/video/minimax-h3
Locale: zh-CN

使用 MiniMax 原生视频接口和 UniAI API Key 调用。

- 服务地址：`https://api.uniai.tv`
- 模型：`MiniMax-H3`、`MiniMax-H3-Max`
- Content-Type：`application/json`

## 接口

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/v2/video_generation` | 创建视频 |
| POST | `/v2/h3_context_ir` | 创建 Context 提示词 |
| POST | `/v2/video_regeneration` | 将 H3 视频再生成至 2K |
| GET | `/v2/query/video_generation/{task_id}` | 查询任务 |
| GET | `/v2/query/video_generation` | 查询任务列表 |
| DELETE | `/v2/video_generation/{task_id}` | 取消或删除任务 |

## 创建视频

帧输入、素材参考、H3 Max、Context 和再生成请求见[调用示例](/models/video/minimax-h3/examples)。

```bash
curl -X POST "https://api.uniai.tv/v2/video_generation" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "A paper boat crosses a quiet pond in warm morning light."
      }
    ],
    "duration": 5,
    "resolution": "768P",
    "ratio": "16:9"
  }'
```

响应：

```json
{
  "task_id": "task_YOUR_VIDEO"
}
```

## 参数

| 字段 | 必填 | 可用值 |
| --- | --- | --- |
| `model` | 是 | `MiniMax-H3` 或 `MiniMax-H3-Max` |
| `content` | 是 | 一条 `text`，可附加媒体项 |
| `duration` | 是 | H3：整数 4–15；H3 Max：整数 5–15 |
| `resolution` | 否 | H3：`768P` 或 `2K`；H3 Max：`480P` 或 `768P`。默认 `768P` |
| `ratio` | 仅文生必填 | 纯文本请求必须使用具体比例；首尾帧使用 `adaptive`；参考素材默认为 `adaptive`。可选：`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`adaptive`。 |
| `aigc_watermark` | 否 | 布尔值，默认 `false` |
| `extra.prompt_expansion_mode` | 仅 H3 Max | `disabled`、`balanced`（默认）或 `quality` |
| `callback_url` | 否 | 公网 HTTP(S) 地址。收到验证请求后 3 秒内原样返回 `challenge`；也可使用查询接口轮询。 |

## 输入图片、视频和音频

媒体放在 `content` 中。每次请求必须有一条 text，最多 7000 个字符。

| 类型 | role |
| --- | --- |
| `image_url` | `first_frame`、`last_frame` 或 `reference_image` |
| `video_url` | `reference_video`；仅再生成时使用 `base_video` |
| `audio_url` | `reference_audio` |

媒体字段使用 `{"url":"https://..."}`。图片未填写 role 时默认为 `first_frame`。首尾帧模式不能与参考素材混用。

首帧示例：

```json
{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "A paper boat crosses a quiet pond in warm morning light."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://YOUR_PUBLIC_URL/first.png"
      },
      "role": "first_frame"
    }
  ],
  "duration": 5,
  "resolution": "768P"
}
```

限制：最多 9 张图片、3 段视频、3 段音频，总计 12 个媒体项。图片支持 JPEG、PNG、WEBP、HEIC、HEIF；每张不超过 30 MB，宽高为 256–5,760 px。视频使用 MP4 或 MOV，每段不超过 50 MB，帧率为 23.976–60 fps；每段 2–15 秒，总长不超过 15 秒。音频使用 WAV 或 MP3，每段不超过 15 MB；每段 2–15 秒，总长不超过 15 秒。使用可公开访问的 URL 或对应 MIME 类型的 data URI。此接口不提供素材上传。

## 查询任务

使用创建响应中的 task ID 轮询：

```bash
curl "https://api.uniai.tv/v2/query/video_generation/task_YOUR_VIDEO" \
  -H "Authorization: Bearer $UNIAI_API_KEY"
```

视频任务响应：

```json
{
  "task": {
    "id": "task_YOUR_VIDEO",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "task_type": "generation",
    "modality": "video",
    "content": {
      "url": "https://YOUR_RESULT_URL/video.mp4"
    }
  }
}
```

状态：`queued`、`running`、`succeeded`、`failed`、`cancelled`。完成后从 `task.content.url` 下载视频。

## Context

Context 返回增强后的提示词，不会生成视频。使用 H3，省略 `resolution`。

```bash
curl -X POST "https://api.uniai.tv/v2/h3_context_ir" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "A paper boat crosses a quiet pond in warm morning light."
      }
    ],
    "duration": 5,
    "ratio": "16:9"
  }'
```

使用相同的任务查询接口；结果提示词位于 `task.content.prompt`。

## 再生成 2K 视频

仅 H3 支持再生成。使用自己账号在最近七天内创建的已完成 H3 768P 任务：

```bash
curl -X POST "https://api.uniai.tv/v2/video_regeneration" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "source_task_id": "task_YOUR_COMPLETED_H3_768P",
    "resolution": "2K"
  }'
```

也可以在 `content` 中传入唯一 `base_video` 项，并附上原始提示词和全部原始输入。不要传 `duration` 或 `ratio`。

## 列表、取消和删除

```bash
curl "https://api.uniai.tv/v2/query/video_generation?page_num=1&page_size=10" \
  -H "Authorization: Bearer $UNIAI_API_KEY"
```

列表响应包含 `items` 和 `total`。可用 `page_num`、`page_size`、`filter.model`、`filter.task_type`、`filter.task_ids` 和 `filter.status` 筛选。原生任务保留七天。

```bash
curl -X DELETE "https://api.uniai.tv/v2/video_generation/task_YOUR_VIDEO" \
  -H "Authorization: Bearer $UNIAI_API_KEY"
```

DELETE 会取消排队中的任务，或删除成功／失败的任务；不能取消运行中的任务。

## 错误

HTTP 错误响应格式：

```json
{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "Invalid request parameters.",
    "http_code": "400"
  },
  "request_id": "opaque_request_id"
}
```

任务失败时查询仍返回任务对象，`task.status` 为 `failed`，错误信息在 `task.error` 中。创建请求超时后，先查询任务，不要直接重复提交。