# H3 视频云 API v5.4

> **与 MiniMax 官方 MiniMax-H3 接口一致**：相同的路径（`POST /v2/video_generation`）、相同的 `content[]` 多模态字段、相同的返回结构与状态语义。已在用官方 H3 SDK 的客户，只需替换 `base_url` 和 API Key 即可接入，**无需任何参数映射**——官方格式的请求原样直传即可，字段对应关系由平台内部处理。
>
> 创建：`POST /v2/video_generation`　查询：`GET /v2/query/video_generation/{task_id}`

## 30 秒上手

**文生视频**（与官方示例同格式）

```bash
curl -X POST "$H3_API_BASE/v2/video_generation" \
  -H "Authorization: Bearer $H3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "一个少年在雨后的山路上奔跑，电影感"}
    ],
    "resolution": "768P",
    "duration": 6,
    "ratio": "16:9"
  }'
```

**图生视频（首帧）——参考图直接传公网 URL**

```bash
curl -X POST "$H3_API_BASE/v2/video_generation" \
  -H "Authorization: Bearer $H3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "人物从门口走向窗边，保持服装和身份一致"},
      {"type": "image_url", "image_url": {"url": "https://你的oss.com/first.jpg"}, "role": "first_frame"}
    ],
    "resolution": "768P",
    "duration": 6
  }'
```

**多模态参考（图 + 视频 + 音频混合）**

```bash
curl -X POST "$H3_API_BASE/v2/video_generation" \
  -H "Authorization: Bearer $H3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "人物跟随参考视频的动作节奏，用参考音频的音色说话。"},
      {"type": "image_url", "image_url": {"url": "https://你的oss.com/ref.jpg"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://你的oss.com/ref.mp4"}, "role": "reference_video"},
      {"type": "audio_url", "audio_url": {"url": "https://你的oss.com/ref.wav"}, "role": "reference_audio"}
    ],
    "resolution": "768P",
    "duration": 10
  }'
```

创建成功返回 `{"task_id":"...","base_resp":{"status_code":0,"status_msg":"success"}}`，随后轮询查询接口拿结果（见第 3 节）。

## 1. Base URL 与鉴权

```
Base URL：https://www.nexusvoidaigc.com
鉴权：所有接口使用 Bearer API Key（平台控制台获取）
```

```bash
export H3_API_BASE="https://www.nexusvoidaigc.com"
export H3_API_KEY="sk-h3-你的密钥"

# 验证连通性
curl -s "$H3_API_BASE/v1/status" -H "Authorization: Bearer $H3_API_KEY"
```

> 请勿把 Key 写入前端公开代码或提交到 git。

## 2. 创建任务：官方字段

`POST /v2/video_generation`，请求体字段与官方 MiniMax-H3 一致：

| 字段 | 类型 | 说明 |
|---|---|---|
| `model` | string | 必填。在售模型为 **MiniMax-H3**，填 `MiniMax-H3`（大小写不敏感）即可；官方其他模型名（如 `MiniMax-H3-Max`）自动映射到在售模型 |
| `content` | array | 必填。多模态输入数组，结构见下方「`content[]` 结构详解」 |
| `duration` | integer | 必填，4–15 秒 |
| `resolution` | string | 必填。官方档 `768P`（推荐）；平台另提供经济档 `576`、`720P`（平台扩展）。`2K` 暂不可用，会显式报错而非静默降级 |
| `ratio` | string | 画幅规则见下方「`ratio` 规则」；枚举：`adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` |
| `callback_url` | string | 可选。状态变更回调（见第 4 节） |
| `aigc_watermark` | boolean | 可选，默认 false |
| `prompt_optimizer` | boolean | 可选（平台扩展），**默认 false**。传 `true` 时平台对 prompt 做结构化改写，会引入额外延迟 |

**`content[]` 结构详解**（与官方一致）：

每个元素通过 `type` 区分类型，用 `role` 标注用途：

```json
[
  {"type": "text", "text": "画面描述（必填，至少一个非空 text）"},
  {"type": "image_url", "image_url": {"url": "https://..."}, "role": "first_frame"},
  {"type": "video_url", "video_url": {"url": "https://..."}, "role": "reference_video"},
  {"type": "audio_url", "audio_url": {"url": "https://..."}, "role": "reference_audio"}
]
```

输入组合与生成场景（与官方一致）：

| 场景 | 组合 |
|---|---|
| 文生视频 | 仅一个 `text` |
| 图生视频·首帧 | `text` + 1 张 `image_url`（`role=first_frame` 或不填） |
| 图生视频·尾帧 | `text` + 1 张 `image_url`（`role=last_frame`） |
| 图生视频·首尾帧 | `text` + 2 张 `image_url`（`role` 分别为 `first_frame`、`last_frame`） |
| 多模态参考生视频 | `text` + `reference_image` / `reference_video` / `reference_audio` 任意组合 |

规则（与官方一致）：

- 每次请求必须包含一个非空 `text`；多素材时每个素材必须显式标注 `role`（单张图片可省略，默认作 `first_frame`）。
- **互斥**：`reference_*` 与 `first_frame` / `last_frame` 不得同时出现。
- 数量：首帧 ≤1、尾帧 ≤1、参考图 ≤9、参考视频 ≤3、参考音频 ≤3。
- 图片 JPG/PNG/WEBP/HEIC，单张 ≤30MB，宽高 256–5760px；视频 MP4/MOV 单个 ≤50MB、2–15 秒；音频 WAV/MP3 单个 ≤15MB、2–15 秒。

**素材引用的三种形式**（各 `*_url` 字段均支持）：

| 形式 | 说明 | 示例 |
|---|---|---|
| 公网 URL | **推荐**。直接传链接，无需预先上传 | `https://oss.xxx.com/ref.jpg` |
| `mm_file://` | （平台扩展）引用已通过上传接口上传的文件 | `mm_file://file-abc123` |
| `data:` Base64 | 内联编码（大文件勿用） | `data:image/png;base64,iVBOR...` |

> **素材保留 48 小时**：平台代收的素材（公网 URL 拉取件与上传文件）在平台保留 **48 小时**，到期自动删除；逾期重用同一素材需重新提供 URL 或重新上传。

**`ratio` 规则**（与官方一致）：

| 场景 | `ratio` |
|---|---|
| 文生视频 | 必填，且不能为 `adaptive` |
| 图生视频（首/尾帧） | 由图片决定画幅，传 `adaptive` 或省略 |
| 多模态参考生视频 | 可选，默认 `adaptive`，也可显式指定 |

**首帧和参考图怎么选**（最容易混淆的一点）：

| 你的需求 | 用哪个 role | 效果 |
|---|---|---|
| 「视频从这张图开始动起来」 | `first_frame` | 图作为视频第 1 帧，画面从它演变 |
| 「照这张图里的人/物做视频」 | `reference_image` | 图只锁定主体形象，画面由 prompt 自由展开 |
| 「开头和结尾都要卡死」 | `first_frame` + `last_frame` | 首尾帧驱动，中间自动过渡 |
| 「跟参考视频的动作/运镜」 | `reference_video` | 动作节奏迁移 |
| 「用参考音频的音色」 | `reference_audio` | 音色/口播驱动 |

## 3. 返回与查询

创建成功：

```json
{"task_id":"424010985738629","base_resp":{"status_code":0,"status_msg":"success"}}
```

查询（与官方一致，task_id 在路径中）：

```http
GET /v2/query/video_generation/{task_id}
Authorization: Bearer sk-xxx
```

成功示例：

```json
{
  "task": {
    "id": "424010985738629",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": "2026-09-14T04:41:14+08:00",
    "content": {"url": "https://输出地址/output.mp4"},
    "resolution": "768x1280",
    "duration": 10,
    "usage": {"total_seconds": 10, "output_seconds": 10, "input_image_count": 1}
  },
  "base_resp": {"status_code": 0, "status_msg": "success"}
}
```

状态枚举（与官方一致）：`queued`、`running`、`succeeded`、`failed`、`cancelled`。成功时从 `task.content.url` 下载成片：**下载链接签名时效 1 小时**（过期重新查询即可获取新链接）；**成片在平台保留 48 小时**，到期自动删除，请及时下载转存。建议每 10 秒轮询一次，不要无限轮询。

**按 file_id 取下载地址**（官方 `files/retrieve` 流程，与官方一致）：使用 V1 兼容格式查询时会返回 `file_id`，可凭它随时换取新的签名下载地址：

```bash
curl -s "$H3_API_BASE/v1/files/retrieve?file_id=file-result-你的task_id" \
  -H "Authorization: Bearer $H3_API_KEY"
# 返回 {"file_id":"file-result-...","download_url":"https://...download?exp=...&sig=..."}
```

## 4. 回调

配置 `callback_url` 后，平台按官方流程先发送带 `challenge` 的验证请求，服务端需在 3 秒内原样返回 `challenge`。验证通过后接收与查询接口一致的任务状态对象（`queued` / `running` / `succeeded` / `failed` / `cancelled`）。建议同时保留轮询兜底。

## 5. 文件上传（可选，平台扩展）

素材不在公网时，可先上传再用 `mm_file://` 引用：

```bash
curl -X POST "$H3_API_BASE/v1/files/upload" \
  -H "Authorization: Bearer $H3_API_KEY" \
  -F "purpose=video_generation" \
  -F "file=@reference.jpg"
# 返回 {"file_id":"file-abc123"}，之后用 mm_file://file-abc123 引用
```

> 大多数场景直接传公网 URL 即可，无需预先上传。上传的文件同样在平台保留 **48 小时**，到期自动删除。

## 6. 官方 V1 兼容格式（Hailuo 老 SDK 迁移）

如果你在用官方 **V1**（Hailuo 系列）SDK，扁平字段格式也原生支持，路径与官方 V1 一致——`POST /v1/video_generation`：

```bash
curl -X POST "$H3_API_BASE/v1/video_generation" \
  -H "Authorization: Bearer $H3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "女孩在咖啡馆里向镜头介绍新品，自然口播",
    "first_frame_image": "https://你的oss.com/first.jpg",
    "duration": 6,
    "resolution": "768P"
  }'
```

| 字段 | 说明 |
|---|---|
| `prompt` | 画面描述（对应 V2 的 `text` 元素） |
| `first_frame_image` / `last_frame_image` | 首帧 / 尾帧图（对应 V2 的 `first_frame` / `last_frame` role） |
| `subject_reference` | 主体参考，格式 `[{"type":"character","image":["https://..."]}]`，`type` 固定 `character`（对应 V2 的 `reference_image` role） |
| `duration` / `resolution` / `callback_url` 等 | 与 V2 相同 |

V1 查询：`GET /v1/query/video_generation?task_id={task_id}`。

> 官方 H3 已统一为 `content[]` 格式，**新项目请使用第 2 节的 V2 接口**；V1 兼容层仅供存量迁移。

## 7. 错误处理

与官方语义一致：401 鉴权、400 参数、402 余额/额度、422 内容或参数不可处理、429 限流、503 算力暂不可用（`暂无可承接该规格的实例`，**未扣费**，可稍后重试或降低档位）、500/529 服务不可用。任何失败响应的 `base_resp.status_code` 均为非 0 且 HTTP 状态码为非 2xx，不会出现"HTTP 200 但无 task_id"的歧义响应。请据此实现重试策略。创建请求不要盲重试——先保存 `task_id`，仅对查询接口重试。

## 8. 上线前检查清单

- 文生视频提供了具体 `ratio`（非 `adaptive`）；带图/参考素材任务使用 `adaptive` 或省略。
- `content[]` 包含至少一个非空 `text`；多素材时每个素材都标了 `role`。
- 没有混用 `first_frame`/`last_frame` 与 `reference_*`（官方互斥，会被 422）。
- 素材 URL 公网可直链访问，格式与大小符合限制。
- `resolution` 使用 `768P`（或平台经济档 `576`/`720P`），`duration` 在 4–15 秒内。
- 查询到 `succeeded` 后确认 `task.content.url` 可下载，并校验 MP4 与音轨。
- 生产环境使用 callback + 轮询兜底，不在客户端暴露 API Key。

## 附录 A：旧版内部接口（迁移说明）

平台早期客户使用的 `POST /v1/video/generations`（`size`/`seconds`/`image_uploads` 参数集）继续可用，仅作存量兼容。**新项目请使用本文档第 2 节的官方 V2 接口**；旧接口参数与官方字段的对应关系：`seconds`→`duration`、`size`→`resolution`、`image_uploads`→`content[]` 中的 `image_url` 元素。需要迁移协助请联系平台。