MiniMax H3 Max API 怎么用？从文字或图片生成视频

MiniMax H3 Max 用文字或首尾帧图片生成 5–15 秒视频，480P 每秒 $0.072，768P 每秒 $0.115。先用下面的纸船提示词生成一条 5 秒横屏短片，768P 预算是 $0.575；接入 API 时，提交一次任务，再用返回的 taskId 获取视频。

MiniMax H3 Max 已在 HiAPI 上线，用这个提示词生成 →。提示词会自动填入，接着手动选择 5 秒、768P、16:9。

第一条视频：雨后的纸船

VIDEO

After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.

用这个提示词生成 →

这条提示词把动作和运镜分开：纸船随水漂动，低机位平滑跟拍，声音用远处鸟鸣交代。把纸船换成自己的主体时，先保留一个动作和一种运镜，容易看清哪处需要调整。

在线试用和 API 接入，怎么选？

想先看效果，打开模型页，复制提示词、选时长和分辨率，再提交生成；已有起始画面时上传首帧图片。做应用接入，则先在 API Key 页面 获取密钥，用服务端请求创建任务，保存 taskId，等任务成功后读取视频地址。

分辨率建议显式写：5 秒 480P 是 $0.36，768P 是 $0.575。先用低分辨率确认动作，再根据交付需要选档；完整预算见 H3 与 H3 Max 价格表。

cURL：创建任务，再查询结果

把 API Key 设置为本机环境变量 HIAPI_API_KEY 后，运行这条请求：

curl --fail-with-body --connect-timeout 10 --max-time 60 -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3-max",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}'

POST 超时、连接中断或返回内容无法确认创建结果时，提交状态未知：先查任务记录，勿直接重跑 POST。确认响应 code=200、data 为对象且 data.taskId 非空后，保存 ID 并替换查询地址里的 YOUR_TASK_ID：

curl --fail-with-body --connect-timeout 10 --max-time 60 "https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

等待中的任务继续查询同一个 ID。data.status 为 success 时，从 data.output 中读取视频条目的 url；为 fail 时检查任务错误信息；输入或认证报错先修正对应问题，已有任务 ID 时继续查询该任务。

Python：提交一次，等待同一个任务

下面使用 Python 标准库。只 POST 一次并校验响应；提交结果未知时停止并提示查任务记录。查询暂时失败会保留任务 ID 并继续 GET，600 秒是本例的等待上限。

import json
import os
import time
import urllib.error
import urllib.request

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer " + os.environ["HIAPI_API_KEY"],
    "Content-Type": "application/json",
}


def request(method, url, body=None):
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(url, data=data, headers=HEADERS, method=method)
    with urllib.request.urlopen(req, timeout=30) as response:
        result = json.load(response)
    if not isinstance(result, dict) or result.get("code") != 200:
        raise ValueError(f"Unexpected API response: {result!r}")
    if not isinstance(result.get("data"), dict):
        raise ValueError("Missing data object")
    return result["data"]


payload = {
  "model": "minimax-h3-max",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}
try:
    created = request("POST", BASE, payload)
    task_id = created.get("taskId")
    if not isinstance(task_id, str) or not task_id.strip():
        raise ValueError("Missing taskId")
except (OSError, ValueError) as exc:
    raise SystemExit(
        f"Submission outcome is unconfirmed: {exc}. "
        "Check task history before another POST; do not blindly resubmit."
    )

print("taskId:", task_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    try:
        task = request("GET", f"{BASE}/{task_id}")
    except urllib.error.HTTPError as exc:
        if exc.code in (400, 401, 403, 404):
            raise SystemExit(
                f"Query rejected ({exc.code}). Correct URL/auth, then GET existing task {task_id}."
            )
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    except (OSError, ValueError) as exc:
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    status = task.get("status")
    if status not in ("queued", "handling", "archiving", "success", "fail"):
        raise RuntimeError(f"Unexpected task status {status!r}; keep task ID {task_id}")
    if status == "success":
        output = task.get("output")
        if not isinstance(output, list):
            raise RuntimeError(f"Invalid output; keep task ID {task_id}")
        videos = [item["url"] for item in output
                  if isinstance(item, dict) and item.get("type") == "video"
                  and isinstance(item.get("url"), str) and item["url"]]
        if not videos:
            raise RuntimeError(f"No video URL; keep task ID {task_id}")
        print(videos[0])
        break
    if status == "fail":
        raise RuntimeError(f"Task {task_id} failed: {task!r}")
    time.sleep(5)
else:
    raise TimeoutError(f"Keep querying existing task {task_id}; do not POST again")

用图片控制首帧或尾帧

要让视频从自己的商品图开始，在 input 中加入 first_frame_image；要指定结尾，则加入 last_frame_image。H3 Max 可以单独传尾帧，也可以同时传首尾帧；传任何帧图片时都省略 aspect_ratio，由图片决定画幅。

下面是首尾帧完整请求体，图片 URL 为你自己的可公开访问地址占位；图片负责交代起始与收尾构图：

{
  "model": "minimax-h3-max",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "first_frame_image": "https://your-domain.com/images/paperboat-first.jpg",
    "last_frame_image": "https://your-domain.com/images/paperboat-last.jpg"
  }
}

只需控制尾帧时，可删去 first_frame_image 并保留 last_frame_image，仍省略 aspect_ratio。只把镜头动作写进提示词，图片负责交代主体和初始构图。多镜头可以在提示词里写清每次切换；请求字段仍使用这张表，勿添加 camera_angle、mode、seed 或 watermark。

纯文字生成目前输出横屏，本次 768P 样片为 1344×768；请求写 9:16 也返回这一横屏尺寸。需要竖屏时，按目标画幅准备首帧图片并省略 aspect_ratio，或在后期裁切、填充。

接进应用时，把回调放在请求顶层

在创建请求的顶层加入可选回调，与 model、input 并列：

{
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}

把这段合进完整请求。接收端按 taskId 去重，成功和失败分开处理，漏掉的通知用任务查询补。拿到任务 ID 后不要重复提交；HTTP 报错先读响应内容，分清是认证问题还是参数问题。

接入后检查这四项

1. 保存非空 data.taskId，查询异常后仍沿用它。
2. 确认终态为 success 或 fail，不把等待上限当作模型耗时。
3. 在成功任务的 data.output 中按 type=video 找视频 URL。
4. 下载产物核对实际尺寸、时长和画面是否符合交付要求。

常见问题

H3 Max 能用参考视频或音频吗？ 需要图片、视频、音频多模态参考时选 MiniMax H3，H3 Max 用文字和首尾帧图片控制画面。

和 H3 相比，Max 更贵吗？ H3 2K 每秒 $0.1189，Max 768P 每秒 $0.115。先按所需分辨率和参考素材选模型，再用时长算预算。

做竖屏短片该怎么开始？ 准备竖版首帧图片，省略 aspect_ratio，让视频跟随图片画幅；需要从文字直接选 9:16 时，可以用 H3。

复制纸船提示词，用这个提示词生成 →，先做一条 5 秒短片。更多动作和运镜写法见 4 个真实视频与完整提示词，完整字段见 H3 Max API 参数文档。