H3 视频云 API v5.4

文档下载： 下载 PDF (.pdf) 下载 Markdown (.md) Python SDK JS SDK

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 秒上手

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

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

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
  }'

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

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（平台控制台获取）

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`（推荐）；平台另提供 `480P`、`576`、`720P`（平台扩展，横屏加 -l）。`1080P` 即将开放（预置定价 0.28元/秒，暂不受理请求）；`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 标注用途：

[
  {"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. 返回与查询

创建成功：

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

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

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

成功示例：

{
  "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，可凭它随时换取新的签名下载地址：

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:// 引用：

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：

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 元素。需要迁移协助请联系平台。