# MiniMax H3 视频

> MiniMax-H3 视频生成、提示词增强、768P 到 2K 再生成，以及任务查询和取消/删除。

Base URL：`https://platform.sgt.site/minimax`

**受理与恢复：**原生提交在发送前持久保存平台任务并冻结资金。发送后断连、超时、5xx、截断成功响应或缺任务 ID 时保持待核对，不自动重复提交或释放资金，且不依赖重试次数设置。错误诊断中的 `task_id` 和 `request_id` 可定位同一平台任务；使用 `/v2/query/video_generation/{task_id}` 查询原任务。未取得可靠上游 ID 时由管理员核对，不重新 POST。原生 `Idempotency-Key` 尚无跨请求重放保证；成功响应仍使用 `task_id`，查询仍使用 `task` 包装。明确未发送或被上游拒绝时才释放本次预留，生成状态与账务状态分开处理。

将 Seedance 的任务 ID 用于本页 H3 单任务查询时返回 HTTP 404；请使用该任务提交时对应的 Seedance 查询路径，不要重新生成。

本文中的接口路径均相对于此 Base URL；完整请求地址由二者拼接。

| 方法 | 路径 |
| --- | --- |
| POST | `/v2/video_generation` |
| GET | `/v2/query/video_generation/{task_id}` |
| GET | `/v2/query/video_generation` |
| DELETE | `/v2/video_generation/{task_id}` |
| POST | `/v2/h3_context_ir` |
| POST | `/v2/video_regeneration` |

<a id="native-h3-section-1"></a>

## 4.1 路径

本页所有生成请求的 `model` 都填写 `MiniMax-H3`，不包含 `MiniMax-H3-Max`。使用平台签发给使用人或应用的虚拟密钥，放在 `Authorization: Bearer <完整虚拟密钥>` 请求头中；JSON 提交需要 `Content-Type: application/json`。

平台分别授权和计价三个动作，管理员需为要使用的动作配置当前企业的有效价格：

| 动作 | 请求中的 `model` | 平台授权与计价名称 | 结果 |
| --- | --- | --- | --- |
| 视频生成 | `MiniMax-H3` | `MiniMax-H3` | 视频 |
| 提示词增强 | `MiniMax-H3` | `MiniMax-H3-Context-IR` | 增强提示词 |
| 视频再生成 | `MiniMax-H3` | `MiniMax-H3-Regeneration` | 2K 视频 |

后两项是计价与授权动作名称，不是请求模型 ID，不应填入 `model`。使用它们还需具有基础 `MiniMax-H3` 的模型权限；它们使用实际 H3 渠道，费用分别按本次动作的价格冻结。

<a id="native-h3-section-2"></a>

## 4.2 参数与素材

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `model` | string | 必填，`MiniMax-H3` |
| `content` | array | 含非空文本，文本最多 7000 字符；建议只放一项文本 |
| `resolution` | string | 必填，`768P/2K` |
| `duration` | integer | 必填，4–15 秒 |
| `ratio` | string | 默认 `adaptive`；纯文本必填且不能为 `adaptive`；其余规则见下文 |
| `aigc_watermark` | boolean | 是否添加 AIGC 标识水印，默认 `false` |
| `callback_url` | string | 可选，平台允许的 HTTPS 接收地址；需要先完成下文的 challenge 验证 |

`content` 的文本、图片、视频、音频对象格式与 Seedance 相同，均为 `type + *_url.url + role`。H3 的模式约束：

- 首帧/尾帧各最多一张，可只传首帧、只传尾帧或首尾帧；此模式比例由输入图片决定，传入其他比例会按 `adaptive` 处理。
- 参考模式最多 9 张图片、3 个视频、3 个音频，role 分别是 `reference_image/reference_video/reference_audio`。
- 首尾帧不能与参考图片/视频/音频混用。
- 无 role 的图片默认作为首帧；若要多图参考，必须显式写 `reference_image`。
- 比例可选 `21:9/16:9/4:3/1:1/3:4/9:16/adaptive`。纯文本不接受 adaptive；参考素材模式省略比例时默认 adaptive。
- `MiniMax-H3-Max` 的 `extra` 字段不在本页范围。素材格式、尺寸、时长要求见 4.5。

<a id="native-h3-section-3"></a>

## 4.3 提交示例

以下五种模式各有完整 Bash / curl 请求。把 `KEY` 换成自己的虚拟密钥，并替换 JSON 中 `example.com` 的素材占位 URL；不要把平台 `file_id` 直接塞进原生 `image_url.url`。素材须符合 4.5 的格式、大小、尺寸与时长要求。每次 POST 都创建一个新任务，提交超时不自动重复提交。

<a id="native-h3-h-0ea604fc"></a>

### 文生视频

只有文本时必须指定具体比例，不能使用 `adaptive`。此例使用最短的 4 秒和 768P。

```bash
BASE_URL="https://platform.sgt.site/minimax"
KEY="YOUR_VIRTUAL_KEY"
curl -sS --request POST "$BASE_URL/v2/video_generation" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "MiniMax-H3",
  "resolution": "768P",
  "duration": 4,
  "aigc_watermark": false,
  "content": [
    {
      "type": "text",
      "text": "白色桌面上的蓝色纸船缓慢转动，固定镜头"
    }
  ],
  "ratio": "16:9"
}'
```
<a id="native-h3-h-8bd3cb58"></a>

### 仅首帧

只提供 `first_frame`；画面从该图片开始。首帧模式由图片决定比例，示例明确使用 `adaptive`，不混入 reference 角色。

```bash
BASE_URL="https://platform.sgt.site/minimax"
KEY="YOUR_VIRTUAL_KEY"
# 将 JSON 中 example.com 的素材 URL 分别替换为你自己的公网素材地址
curl -sS --request POST "$BASE_URL/v2/video_generation" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "MiniMax-H3",
  "resolution": "768P",
  "duration": 4,
  "aigc_watermark": false,
  "content": [
    {
      "type": "text",
      "text": "以首帧为起点，纸船向画面右侧轻轻移动"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/inputs/start.png"
      },
      "role": "first_frame"
    }
  ],
  "ratio": "adaptive"
}'
```
<a id="native-h3-h-28cee3db"></a>

### 仅尾帧

H3 支持只传 `last_frame`，**无需补一张首帧**。视频朝给定尾帧结束，仍需文本；不要把其他视频系列“尾帧必须搭配首帧”的规则套到这里。

```bash
BASE_URL="https://platform.sgt.site/minimax"
KEY="YOUR_VIRTUAL_KEY"
# 将 JSON 中 example.com 的素材 URL 分别替换为你自己的公网素材地址
curl -sS --request POST "$BASE_URL/v2/video_generation" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "MiniMax-H3",
  "resolution": "768P",
  "duration": 4,
  "aigc_watermark": false,
  "content": [
    {
      "type": "text",
      "text": "纸船从远处缓慢靠近，在给定尾帧的构图与位置停下"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/inputs/finish.png"
      },
      "role": "last_frame"
    }
  ],
  "ratio": "adaptive"
}'
```
<a id="native-h3-h-a44f24ac"></a>

### 首尾帧

两张图片分别标记 `first_frame` 和 `last_frame`，每个角色最多一张。保持同一主体和兼容构图有助于连贯过渡；不要再添加参考图、参考视频或参考音频。

```bash
BASE_URL="https://platform.sgt.site/minimax"
KEY="YOUR_VIRTUAL_KEY"
# 将 JSON 中 example.com 的素材 URL 分别替换为你自己的公网素材地址
curl -sS --request POST "$BASE_URL/v2/video_generation" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "MiniMax-H3",
  "resolution": "768P",
  "duration": 4,
  "aigc_watermark": false,
  "content": [
    {
      "type": "text",
      "text": "保持纸船外观一致，从首帧平滑移动到尾帧"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/inputs/start.png"
      },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/inputs/finish.png"
      },
      "role": "last_frame"
    }
  ],
  "ratio": "adaptive"
}'
```
<a id="native-h3-h-b5ea8197"></a>

### 多模态参考

此例独立使用一张参考图、一个参考视频和一个参考音频；三种媒体不是必须全部提供，可以按需要选用组合。所有角色都使用 `reference_*`，不能出现首帧或尾帧。参考模式允许具体比例，也可用 `adaptive`；此例选择 `16:9`。

```bash
BASE_URL="https://platform.sgt.site/minimax"
KEY="YOUR_VIRTUAL_KEY"
# 将 JSON 中 example.com 的素材 URL 分别替换为你自己的公网素材地址
curl -sS --request POST "$BASE_URL/v2/video_generation" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "MiniMax-H3",
  "resolution": "768P",
  "duration": 4,
  "aigc_watermark": false,
  "content": [
    {
      "type": "text",
      "text": "按参考图保持蓝色纸船外观，参考视频的移动节奏，参考音频的自然环境声"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/inputs/reference.png"
      },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/inputs/motion.mp4"
      },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": {
        "url": "https://example.com/inputs/ambience.mp3"
      },
      "role": "reference_audio"
    }
  ],
  "ratio": "16:9"
}'
```
五种模式的提交响应都返回平台任务 ID：

```json
{"task_id":"task_example"}
```

保存实际 `task_id`，按下一节查询至终态后读取 `task.content.url`。五种请求都可能产生费用；切换输入模式不意味着免费，尤其参考视频可能计入输入用量。首/尾帧模式传入其他 ratio 会按 adaptive 处理；模式互斥、重复帧角色或数量超限在发送前拒绝。

<a id="native-h3-section-4"></a>

## 4.4 查询响应

```bash
BASE_URL="https://platform.sgt.site/minimax"
curl -X GET "$BASE_URL/v2/query/video_generation/task_example" \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY'
```

成功结果示例：

```json
{
  "task": {
    "id": "task_example",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "content": {
      "url": "https://media.example.com/generated-video.mp4"
    },
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9"
  }
}
```

`task.status` 使用 `queued/running/succeeded/failed/cancelled`。失败信息在 `task.error`，实际用量在可用时由 `task.usage` 提供。视频从 `task.content.url` 读取，Context-IR 的增强提示词从 `task.content.prompt` 读取。`task.task_type` 用 `generation`、`h3_context_ir`、`regeneration` 区分动作。

原生 H3 任务不支持通过通用 `https://platform.sgt.site/v1/videos/{id}` 或其 `/content` 下载入口读取。


轮询同一任务并下载视频（已安装 `jq`）：

```bash
BASE_URL="https://platform.sgt.site/minimax"
KEY="YOUR_VIRTUAL_KEY"
TASK_ID="YOUR_PLATFORM_TASK_ID"
while true; do
  curl -sS --fail-with-body "$BASE_URL/v2/query/video_generation/$TASK_ID" \
    -H "Authorization: Bearer $KEY" > h3-result.json || exit 1
  STATUS=$(jq -r '.task.status' h3-result.json)
  case "$STATUS" in
    queued|running) sleep 5 ;;
    succeeded) break ;;
    failed|cancelled) cat h3-result.json; exit 1 ;;
    *) echo "结果待核对，保留任务 ID，不重新提交"; cat h3-result.json; exit 2 ;;
  esac
done
VIDEO_URL=$(jq -r '.task.content.url // empty' h3-result.json)
test -n "$VIDEO_URL" || { echo "任务完成但缺少视频地址"; exit 1; }
curl -fL "$VIDEO_URL" -o h3-output.mp4
```

<a id="native-h3-section-5"></a>

## 4.5 官方接口与输入限制

官方接口：`POST https://api.minimax.cn/v2/video_generation`，查询 `GET https://api.minimax.cn/v2/query/video_generation/{task_id}`。平台 Base URL 已包含厂商前缀 `/minimax`，使用本页 Base URL 加上述相对路径和虚拟密钥，请求与响应保持原生格式。

| 素材 | 要求 |
| --- | --- |
| 请求体 | 总大小不超过 64 MB，大文件请用公网 URL，不要用 Base64 |
| 文本 | 每次必须包含一个非空 `text`，最多 7000 个字符 |
| 图片 `image_url` | JPG、JPEG、PNG、WEBP、HEIC、HEIF；单张不超过 30 MB；宽、高均在 [256, 5760] px；宽高比 [0.4, 2.5]；首帧 ≤ 1、尾帧 ≤ 1、参考图 ≤ 9 |
| 视频 `video_url`（仅多模态参考） | MP4、MOV；视频编码 H.264/AVC、H.265/HEVC，音频 AAC、MP3；单个不超过 50 MB；最多 3 个；单段 [2, 15] 秒、合计不超过 15 秒；宽、高 [256, 5760] px；宽高比 [0.4, 2.5]；帧率 [23.976, 60] |
| 音频 `audio_url`（仅多模态参考） | WAV、MP3；单个不超过 15 MB；最多 3 个；单段 [2, 15] 秒、合计不超过 15 秒 |

图生视频（首帧/尾帧）与多模态参考生视频互斥，同一请求中出现任一 `reference_*` 就不能再出现 `first_frame`/`last_frame`。

<a id="native-h3-h-45198843"></a>

## 4.6 提示词增强：Context-IR

使用 `POST /v2/h3_context_ir`。此动作只生成文字，不自动创建视频，也不会自动发起第二笔生成费用。

| 字段 | 类型 | 必填 | 规则 |
| --- | --- | --- | --- |
| `model` | string | 是 | `MiniMax-H3` |
| `content` | array | 是 | 至少包含一个非空 `text`，每项文本最多 7000 字符；参考素材角色与普通 H3 相同 |
| `duration` | integer | 是 | 目标视频时长，4–15 秒 |
| `ratio` | string | 条件必填 | 纯文本必须指定具体比例；首尾帧按 adaptive；参考模式默认 adaptive |
| `callback_url` | string | 否 | 需完成接收地址验证 |

不接受 `resolution`、`aigc_watermark` 或 `source_task_id`。

```bash
BASE_URL="https://platform.sgt.site/minimax"
KEY="替换为你的完整虚拟密钥"
curl --request POST "$BASE_URL/v2/h3_context_ir" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data '{"model":"MiniMax-H3","content":[{"type":"text","text":"蓝色纸船在平静水面缓慢漂动，日光，固定镜头"}],"duration":4,"ratio":"16:9"}'
```

HTTP 200 返回 `{"task_id":"task_example"}`。使用本页的单任务查询接口等待完成；以下是成功响应的字段节选：

```json
{
  "task": {
    "id": "task_example",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "task_type": "h3_context_ir",
    "content": {"type": "text", "prompt": "增强后的完整提示词……"},
    "usage": {"prompt_tokens": 1000, "completion_tokens": 2000, "total_tokens": 3000}
  }
}
```

保留完整的 `content.prompt`，自行决定是否发起后续视频生成。费用按输入和输出 token 分别计算；需要独立动作价格及平台配置的输入/输出预留估计。缺少配置会在 Provider 请求前拒绝；缺少可信 token 用量或实际用量超过冻结估计时保留待核对，不改用视频按秒价。

<a id="native-h3-h-534f34f0"></a>

## 4.7 视频再生成：768P 到 2K

使用 `POST /v2/video_regeneration`。这不是任意视频的通用放大接口：源视频必须符合 H3 768P 输出规格，目标 `resolution` 必须为 `2K`。两种输入模式只能选择一种，不能同时发送 `source_task_id` 和 `content`。

<a id="native-h3-h-5e184c4d"></a>

### 按源视频再生成

`content` 中必须有且只有一个 `type: "video_url"`、`role: "base_video"`，并完整附上生成该视频时实际使用的文本与参考素材。文本使用 Context-IR 处理后的最终提示词（如果当时使用过），最多 40,000 字符。

```bash
BASE_URL="https://platform.sgt.site/minimax"
KEY="替换为你的完整虚拟密钥"
curl --request POST "$BASE_URL/v2/video_regeneration" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data '{"model":"MiniMax-H3","resolution":"2K","content":[{"type":"text","text":"替换为生成原视频时实际使用的完整最终提示词"},{"type":"video_url","video_url":{"url":"https://media.example.com/h3-768p.mp4"},"role":"base_video"}],"aigc_watermark":false}'
```

上例适用于原视频只有文字输入的情况；使用过参考图片、视频或音频时，必须一并附上原素材。不要重新填写 `duration` 或 `ratio`。源视频 URL 必须替换为实际可读取的 H3 768P 视频。

| 源视频属性 | 官方要求 |
| --- | --- |
| 音轨 | 必须包含音轨 |
| 帧率 | 24 fps |
| 宽和高 | 均为 32 的整数倍 |
| 像素面积 | 589,824–1,032,192 像素 |
| 总帧数 | 107–362 帧，按 17 帧递增 |

这条模式不要求存在平台源任务。平台校验已有可信尺寸、大小和时长；不会为验证任意外链而额外下载或探测，未掌握的音轨、帧率等由上游校验。工作流支持 HTTP(S) 与 data URL；账号级 `mm_file://` 没有平台归属映射时明确拒绝。

<a id="native-h3-h-a2e94277"></a>

### 按平台源任务再生成

此模式要求原上游账号已开通官方白名单，并由平台记录该身份的能力。未满足条件时返回受控错误，不会发送付费请求试探，也不会自动退回到 base_video 模式。

```bash
BASE_URL="https://platform.sgt.site/minimax"
KEY="替换为你的完整虚拟密钥"
curl --request POST "$BASE_URL/v2/video_regeneration" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  --data '{"model":"MiniMax-H3","source_task_id":"替换为成功的768P平台任务ID","resolution":"2K","aigc_watermark":false}'
```

源任务必须属于当前消费主体、企业与原生协议，是七天内成功的普通 H3 768P 生成，并有可验证的原始上下文和上游 ID。平台固定原渠道、模型映射和原 Key；这些条件失效时拒绝调用。源任务被新生成占用时不能删除。

两种模式均返回新的 `task_id`，按 `task_type: "regeneration"` 查询。再生成使用本次独立价格，原输入视频和超过免费数量的参考图可能再次计费；base_video 本身不计为“原参考视频”。本次预留不是最终收费，完成后按真实输出秒数、原输入视频秒数和图片数量结算；缺少证据保持待核对。

<a id="native-h3-h-816dcab5"></a>

## 4.8 任务列表与取消/删除

列表只包含当前主体、企业及当前模型权限可见的原生任务，不枚举共享上游账号。先过滤权限和最近七天的上游创建时间，再分页。

```bash
BASE_URL="https://platform.sgt.site/minimax"
KEY="替换为你的完整虚拟密钥"
curl --request GET "$BASE_URL/v2/query/video_generation?page_num=1&page_size=20&filter.status=succeeded" \
  -H "Authorization: Bearer $KEY"
```

| 查询参数 | 默认与允许值 |
| --- | --- |
| `page_num` | 默认 1，平台允许 1–10000 |
| `page_size` | 默认 20，平台允许 1–100 |
| `filter.status` | 可选 `queued/running/succeeded/failed/cancelled` |
| `filter.task_ids` | 可选平台任务 ID；多个 ID 可重复参数或用逗号分隔 |
| `filter.model` | 可选，使用请求模型名 `MiniMax-H3` |
| `filter.task_type` | 可选 `generation/h3_context_ir/regeneration` |

HTTP 200 返回 `{"items":[...],"total":1}`，每个 `items` 元素是单任务查询中 `task` 内的对象；无结果时为 `{"items":[],"total":0}`。显式 ID 筛选也不能绕过七天窗口。列表与单任务查询不新增生成费用。

取消或删除：

```bash
BASE_URL="https://platform.sgt.site/minimax"
KEY="替换为你的完整虚拟密钥"
curl --request DELETE "$BASE_URL/v2/video_generation/task_example" \
  -H "Authorization: Bearer $KEY"
```

| 任务状态 | 结果 |
| --- | --- |
| `queued` | 确认取消后返回 `{"task_id":"task_example","action":"cancelled","status":"cancelled"}`；释放未消费预留 |
| `succeeded`、`failed` | 确认删除后返回 `action/status: "deleted"`；删除成功任务不退费 |
| `running`、`cancelled` | 返回 HTTP 400，不执行取消或删除 |
| 被后续生成占用 | 返回 HTTP 409，保留源任务 |
| 受理、删除结果或账务待核对 | 返回受控的 409/503，继续核对同一任务，不重新生成 |

有效但已用尽额度的密钥仍可列出已有任务或请求删除，当前身份、IP、组织和模型权限仍需有效。

<a id="native-h3-h-142055c2"></a>

## 4.9 回调

可在生成请求中提供 `callback_url`。平台先发送 `{"challenge":"随机字符串"}`，接收端须在 3 秒内以 JSON 原样回显同一 challenge；验证失败时不会创建生成任务。默认只接受允许访问的 HTTPS 地址，特殊网络目标需管理员先明确授权。

后续回调由平台已持久化的查询事实触发，正文沿用本页的 `{"task":{...}}` 查询包装和平台任务 ID。接收端应按事件 ID 去重；通知可能因轮询或重试延迟，不能假设收到每个中间状态。投递失败不会重新生成或改变已经确认的账单。

平台通知使用 `X-Heighliner-Event-Id`、`X-Heighliner-Event-Sequence` 和 `X-Heighliner-Signature`。按[任务回调与验签](task-callbacks.md)验证平台签名并去重，保留原始 HTTP 正文；challenge 验证请求不是任务事件，不套用任务事件的签名结构。