MiniMax-H3 视频生成 API

01 概览

H3 是一个全模态视频生成模型,在一次前向里联合生成画面与同步立体声(人声、音效、音乐)。接口为异步:提交任务立即拿到 id,再轮询状态、完成后取件。

02 鉴权

每个请求(提交/查询/下载)都需在请求头带上 Bearer Token,否则返回 401。Token 校验在 nginx 网关层完成,后端服务只监听内网,外部扫描无法直连。

Authorization: Bearer h3-c7203631286407cd4e86136b11b4ab2e8cc601f5879902ce

03 快速开始

文生视频(t2va),8 步快档,约 2–3 分钟出片。三个必填字段:task、target、prompt。

curl https://h3.yiling.ink/v1/videos \
  -H "Authorization: Bearer h3-c72036…901f5879902ce" \
  -F task=t2va \
  -F 'target={"short_edge":768,"aspect_ratio":"16:9","duration_seconds":5}' \
  -F prompt=一只橘猫在钢琴键上散步,阳光洒进房间,轻柔的钢琴声 \
  -F num_inference_steps=8 \
  -F seed=42

# → {"id":"7932b6bd-…","status":"queued","progress":0, …}

import requests, time

BASE  = "https://h3.yiling.ink"
TOKEN = "h3-c7203631286407cd4e86136b11b4ab2e8cc601f5879902ce"
H     = {"Authorization": f"Bearer {TOKEN}"}

# 1) 提交任务(multipart 表单)
r = requests.post(f"{BASE}/v1/videos", headers=H, data={
    "task": "t2va",
    "target": '{"short_edge":768,"aspect_ratio":"16:9","duration_seconds":5}',
    "prompt": "一只橘猫在钢琴键上散步,阳光洒进房间",
    "num_inference_steps": 8,
    "seed": 42,
})
vid = r.json()["id"]

# 2) 轮询直到完成
while True:
    s = requests.get(f"{BASE}/v1/videos/{vid}", headers=H).json()
    if s["status"] in ("completed", "failed"): break
    time.sleep(5)

# 3) 取件:s["inference_time_s"], s["file_paths"], 或 /content 下载
print(s["status"], s["inference_time_s"])

04 端点

辅助端点:GET /health 健康检查 · GET /model_info 模型信息 · GET /openapi.json 完整 schema。

05 请求参数

POST /v1/videos 使用 multipart/form-data。下表为常用字段;标红的三项必填。

核心字段

target 输出规格对象

条件输入:conditions(官方推荐,fl2va / ref2va 用)

conditions 是一个 JSON 数组,每个元素声明一件参考素材(与官方 MiniMax-H3 请求格式一致):

"conditions": [
  {"role": "keyframe",  "type": "image", "uri": "data:image/jpeg;base64,…", "frame_index": 0},   // fl2va 首帧
  {"role": "reference", "type": "image", "uri": "https://…/face.png"},                            // ref2va 参考图
  {"role": "reference", "type": "video", "uri": "data:video/mp4;base64,…"}                        // ref2va 参考视频
]

subject_definitions:
<Subject 1> is the person whose appearance comes from <Picture 1>
and whose dance motion comes from <Video 1>.

summary:
[reference generation] The target video shows <Subject 1> performing
the motion of <Video 1> …

retention_analysis:
<Subject 1>: fully_preserved - identity and appearance follow <Picture 1>.
<Video 1> (motion structure): attribute_transfer - the motion is
transferred to <Subject 1>; the original performer is not preserved.

detailed_description:
[Shot 1] …(按官方 Prompt 指南逐镜头描述)

"conditions": [
  {"role": "identity", "type": "image", "uri": "…"},   // 人物身份(别名 subject/face/appearance/character)
  {"role": "motion",   "type": "video", "uri": "…"},   // 动作驱动(别名 action/drive/driving/pose)
  {"role": "voice",    "type": "audio", "uri": "…"}    // 音色参考(别名 timbre,可选)
]

条件输入:兼容字段(sglang 通用通道,已实测可用)

增强与输出(可选)

完整字段(含 fps、num_frames、size、true_cfg_scale、max_sequence_length、extra_body 等)以 GET /openapi.json 为准。

06 三种任务模式

由 task 字段选择。当前服务加载的是 Ref2VA 检查点(+ 官方 ref2v_turbo_4step_v0.1 LoRA,按 8 步推理),支持 ref2va;t2va / fl2va 为 FL2VA 检查点能力,需切换服务(显存无法双开)。带参考图请求请显式传 task=ref2va,否则网关默认推导为 fl2va 会被当前后端拒绝。

curl https://h3.yiling.ink/v1/videos \
  -H "Authorization: Bearer $TOKEN" \
  -F task=fl2va \
  -F 'target={"short_edge":768,"aspect_ratio":"16:9","duration_seconds":5}' \
  -F prompt=镜头缓缓推近,人物微笑转头 \
  -F input_reference=@first_frame.png \
  -F num_inference_steps=8

07 响应结构

提交与查询都返回同一个 VideoResponse 对象。关键字段:

{
  "id": "7932b6bd-c572-4b0a-b04b-429578587f94",
  "status": "completed",   "progress": 100,
  "size": "1366x768",      "seconds": "5.166667",
  "inference_time_s": 139.58,
  "peak_memory_mb": 36506.0,
  "file_paths": ["outputs/7932b6bd-….mp4"]
}

08 异步流程

视频生成耗时以分钟计,接口设计为异步三段式。提交后客户端无需保持长连接,拿 id 走人,之后轮询即可。

09 预设与样片

同一 prompt、同一 1344×768 / 5 秒规格,在双 A800 上的实测三档。步数越少越快,画质略降。点卡片播放样片。

10 能力与限制

11 任务队列(持久化网关)

所有请求经一层持久化网关(FastAPI + SQLite,systemd 守护)进入 H3 引擎。任务落库,服务/服务器重启也不丢,中断的自动续跑。

轮询 GET /v1/videos/{id} 会多返回:queue_ahead(排队时前面还有几个)、created_at、完成后 url(下载地址)。GET /health 返回实时队列深度 {status, queued, running, backend}。

12 接入 New API

本接口兼容 New API(newapi.pro)的 OpenAI 视频(Sora)格式,可直接加为一个渠道。

零改兼容:task / target 自动补全

H3 特有的 task、target 在网关侧可选,不传会自动推导,所以标准 Sora 请求直接能用:

纯 Sora 客户端要覆盖 H3 参数,放 metadata(JSON 字符串):metadata={"task":"fl2va","num_inference_steps":8,"guidance_scale":1.0}。

curl https://h3.yiling.ink/v1/videos \
  -H "Authorization: Bearer $TOKEN" \
  -F prompt=a red sports car on a coastal road at sunset \
  -F model=MiniMax-H3 -F size=1280x720 -F seconds=5
# 无需 task/target,网关自动补全 → 正常生成