MiniMax H3 · Video Generation API

视频生成 API

提交任务 → 轮询状态 → 下载视频。接口结构与 MiniMax 官方视频 API 一致， 已有脚本只需替换 base_url 与 API Key。

base_url · — API Key · —

1. 鉴权

所有 /v1 接口需要携带请求头：

Authorization: Bearer —

也接受 X-API-Key: <key>。缺少或错误返回 401。

2. 上传参考素材

参考图 / 参考视频 / 参考音频需先上传，拿到 file_id 后在创建任务时引用。 同一个文件重复上传会返回同一个 id。

curl -X POST /v1/files/upload \
  -H "Authorization: Bearer " \
  -F "files=@person.png" \
  -F "files=@car.png" \
  -F "files=@street.png"

{
  "files": [
    {"file_id": "file_6159f1b87149", "kind": "image", "name": "person.png", "size": 1793346},
    {"file_id": "file_07ef78e9d465", "kind": "image", "name": "car.png",    "size": 2726058}
  ],
  "base_resp": {"status_code": 0, "status_msg": "success"}
}

支持 png / jpg / webp / bmp / gif / mp4 / mov / webm / wav / mp3 / flac，单文件上限 2 GB。

3. 创建生成任务

curl -X POST /v1/video_generation \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{
    "model": "h3-pulpcut",
    "prompt": "subject_definitions:\n<Subject 1> is the young woman in <Picture 1> ...",
    "resolution": "1080P",
    "duration": 15,
    "seed": 771002,
    "ref_images": ["file_6159f1b87149", "file_07ef78e9d465", "file_57ca65cd8149"]
  }'

{
  "task_id": "a2e3128b",
  "file_id": "f_a2e3128b",
  "base_resp": {"status_code": 0, "status_msg": "success"}
}

4. 查询任务

curl "/v1/query/video_generation?task_id=a2e3128b" \
  -H "Authorization: Bearer "

{
  "task_id": "a2e3128b",
  "status": "Processing",
  "file_id": "f_a2e3128b",
  "model": "h3-pulpcut",
  "base_resp": {"status_code": 0, "status_msg": "success"}
}

5. 获取下载链接

curl "/v1/files/retrieve?file_id=f_a2e3128b" \
  -H "Authorization: Bearer "

{
  "file": {
    "file_id": "f_a2e3128b",
    "download_url": "https://h3.firstarpc.com/v1/files/web_00001_.mp4",
    "expires_in": 3600
  },
  "base_resp": {"status_code": 0, "status_msg": "success"}
}

download_url 为相对路径，直接拼接 base_url 即可下载，支持断点续传（HTTP Range）。

6. 完整示例（Python）

import time, requests

BASE = ""
KEY  = ""
H    = {"Authorization": f"Bearer {KEY}"}

# 1) 上传参考图
files = [("files", open(p, "rb")) for p in ("person.png", "car.png", "street.png")]
ids = [f["file_id"] for f in
       requests.post(f"{BASE}/v1/files/upload", headers=H, files=files).json()["files"]]

# 2) 创建任务
task = requests.post(f"{BASE}/v1/video_generation", headers=H, json={
    "model": "h3-pulpcut",
    "prompt": open("prompt.txt", encoding="utf-8").read(),
    "resolution": "1080P",
    "duration": 15,
    "ref_images": ids,
}).json()
tid = task["task_id"]
print("task:", tid)

# 3) 轮询
while True:
    q = requests.get(f"{BASE}/v1/query/video_generation",
                     headers=H, params={"task_id": tid}).json()
    print(q["status"])
    if q["status"] in ("Success", "Fail"):
        break
    time.sleep(10)

# 4) 下载
if q["status"] == "Success":
    f = requests.get(f"{BASE}/v1/files/retrieve",
                     headers=H, params={"file_id": q["file_id"]}).json()["file"]
    mp4 = requests.get(BASE + f["download_url"])
    open("out.mp4", "wb").write(mp4.content)

7. 错误码

8. 限制与约定