你的 MiniMax H3 轮询循环永远不会退出。这是真正能完成的教程。

你的第一次 POST 请求在十秒内就返回了一个 task_id。看起来像是一次胜利。

然后六分钟过去，毫无动静。你照着某个教程抄了 while status != "Success"，结果循环一直空转，因为这个端点早就不返回 Success 这个词了。于是你改用 Webhook。一个推送都没收到，而且没有任何地方告诉你原因。第二天早上你回去看昨天的渲染结果，链接返回 404。

这四件事看起来互不相干。没有哪一件是模型的错。这四件事全部源于异步契约，而几乎没有人把它写下来。下面就是完整的契约，外加一个从另一端产出的真实双镜头短片。

关键要点

• 三个端点，一个循环：create 返回一个 task_id 然后挂断，你轮询，你下载。所有困难的事情都在 create 调用之后。
• 真正的五个状态是 queued、running、succeeded、failed、cancelled。没有 expired 状态，不管哪个博客文章告诉你的。
• 有两样东西确实会过期，但它们都不是状态：下载 URL 有时限，任务记录本身也只能查询 7 天。
• 如果你使用回调，MiniMax 会先发送一个包含 challenge 字段的验证请求，你必须在 3 秒内原样返回它。如果失败，你不会收到任何错误，只会永远沉默。
• 对于纯文本生成，ratio 是必需的，并且不能是 adaptive。对于图生视频，第一帧决定了画面比例，你传入的任何 ratio 都会被忽略。

先看成品

本教程的完整成果：两个 MiniMax H3 镜头，2K 分辨率，拼接后时长 14.6 秒。镜头 A 是从生成的第一帧进行图生视频，镜头 B 是文生视频。请打开声音。音频不是后期配的音轨，H3 在同一代中渲染了齿轮声、雨声和低语声。

制作它用了三个 API 调用：一个图像模型生成第一帧，两个 H3 端点生成镜头，一行 ffmpeg 命令拼接它们。下面的代码就是实现这一切的代码。

为什么大多数 MiniMax H3 教程在第二次请求时会失败

几乎所有针对这个模型的指南都止步于 create 调用。那是简单的一半。create 调用验证你的负载，交给你一个 task_id 然后断开连接，然后你独自面对一个需要几分钟才能完成的任务，以及一套无人打印的规则。

失败重复得令人厌烦。我在一个下午就遇到了下面六种中的五种。

第一行是那种能吞噬整个晚上的一行，值得精确说明。MiniMax 较旧的视频 API 使用大写单词报告进度，例如 Preparing / Queueing / Processing / Success / Fail。H3 使用的 v2 查询端点返回 queued、running、succeeded、failed、cancelled（MiniMax API 参考，2026 年 8 月）。许多第三方经销商文档仍然打印旧的集合，或者在一页中混用两者。如果你继承了一个来自那些文档的循环，它永远无法终止，因为它等待的字符串永远不会被发送。

MiniMax H3 教程工作流程：三个端点，五种状态，一个循环

H3 于 2026 年 7 月 31 日发布，作为一个全模态视频模型：文本、图像、视频和音频都存在于同一个上下文窗口中，输出最长 15 秒、2K 分辨率，带有原生立体声音频（MarkTechPost，2026 年 8 月）。对于 API，这意味着一个 create 端点带有一个 content 数组，你在数组中放入什么决定了你处于哪种模式。

以及你的代码实际需要处理的部分。五种状态，五种不同分支。

没有 expired 状态。这个词经常被与该 API 关联，但它属于另外两样东西：下载 URL（有时限且可刷新）和任务记录（仅可查询最近 7 天）。两者都在第 4 步中涵盖。

在代码之前还有一个数字。H3 上视频生成的并发限制是按连接数而非每分钟请求数计算的：免费层 2 个并发任务，付费后 15 个（MiniMax 速率限制，2026 年 8 月）。超过限制你会立即收到 429。没有为你排队。我也曾通过路由网关推送 20 个并发 H3 任务，全部成功落地，也曾有一天在相同设置下遇到 429，所以请将任何高于文档限制的数字视为天气，而非常数。

直接使用还是通过网关

三个步骤无论哪种方式都相同，但字符串不同，这在凌晨 1 点调试时很关键。

我之所以通过 网关 运行本教程的链，纯粹是因为倒数第二行：第一帧来自 OpenAI 图像模型，两个镜头来自 MiniMax，我不想为一部 14 秒的短片处理两个供应商、两个密钥和两个账单页面。如果你已经在 MiniMax 平台内，就留在那里，下面的循环除了路径和状态词之外无需改动即可使用。

Hailuo AI 视频生成器：在写任何代码之前如何使用

如果你搜索“如何使用 Hailuo AI 视频生成器”来到这里，你来对地方了，而且你暂时不需要任何代码。Hailuo 是 MiniMax 面向消费者的应用，H3 是 API 使用的模型名称。同一引擎，不同入口。

三分钟，无需终端：

1. 打开一个模型页面，例如 MiniMax H3 图生视频。游乐场在页面的右侧面板。
2. 放入一张首帧图像，或者切换到文生视频页面直接写提示词。设置分辨率和时长。大声说出你想听到的声音，而不仅仅是看到的画面：H3 在同一轮中生成音频，所以“雨滴敲击玻璃，微小的伺服电机咔哒声”是真实的指令，而非装饰。
3. 点击运行。按钮会显示你选择的确切费用，然后在提交前确认。等待，下载。

这就是完整的无代码路径，对于一次性片段来说，它确实是更快的选择。当你需要十个变体，或者由另一个模型生成并直接输入的首帧时，再回到代码。这就是本文剩余部分的内容。

MiniMax H3 教程：创建、轮询、下载、重复

一个示例贯穿所有七个步骤：一位钟表匠修理一只小型的黄铜机械鸟，对它低语一句，然后鸟飞出作坊。两个镜头。镜头 A 是图生视频，因此室内场景经过艺术指导。镜头 B 是文生视频，因为没有天空的源帧。

第 1 步：使用 GPT Image 2 生成第一帧

图生视频忽略 ratio，因此第一帧就是你决定镜头 A 画面比例的地方。以 16:9 和最高质量级别生成它，因为 H3 会继承其中的每一个瑕疵，然后再加上运动模糊。

模型：openai/gpt-image-2/text-to-image。设置：质量 high，2048x1152，16:9，PNG。

textCopy
1一个杂乱的钟表匠作坊在黄昏时分，温暖的白炽灯照在一张布满疤痕的橡木工作台上。一位穿着皮围裙的老修理工俯身靠近一只小黄铜机械鸟，鸟静静地躺在他合拢的掌心中，翅膀半开，微小的齿轮可见。雨水从身后的有竖框窗户流下；一个煤炉在画面左侧发出琥珀色光芒。浅景深，35mm，灯光光束中充满体积感灰尘，深琥珀色和青色调色板，照片级真实感，无文字。
2

Atlas Cloud 上的 GPT Image 2 游乐场，带有本教程的首帧提示词和输出面板中的渲染钟表匠作坊

Atlas Cloud 上的 GPT Image 2，质量 high，2048x1152。运行按钮在你提交前显示所选设置的确切费用，本张为 $0.1745。

保留返回的 URL。第 2 步将其直接输入 H3，无需下载往返。

第 2 步：创建 MiniMax H3 任务并保存 task_id

create 调用做两件事然后就不再关心你：它验证负载并返回一个 task_id。这里的 400 表示你的负载有问题，而非瞬时故障，所以不要将其放在重试循环后面。所有其他类型的问题会在轮询期间出现。

一个能真正省钱的习惯：在做任何其他事情之前先持久化 task_id。任务只可查询 7 天，如果你的进程在内存中持有 id 时死亡，你就为无法再访问的渲染支付了费用。

pythonCopy
1import os, json, time, requests
2
3BASE = "https://api.minimax.io"
4HEADERS = {
5    "Authorization": f"Bearer {os.environ['MINIMAX_API_KEY']}",
6    "Content-Type": "application/json",
7}
8
9def create_task(payload: dict) -> str:
10    r = requests.post(f"{BASE}/v2/video_generation",
11                      headers=HEADERS, json=payload, timeout=60)
12    if r.status_code == 400:
13        # 你的负载错误。重试只会再次错误。
14        raise ValueError(f"被拒绝: {r.text}")
15    r.raise_for_status()
16    task_id = r.json()["task_id"]
17    with open("tasks.jsonl", "a") as f:                 # 在做任何其他事情之前持久化
18        f.write(json.dumps({"task_id": task_id, "at": int(time.time()),
19                            "payload": payload}) + "\n")
20    return task_id
21
22SHOT_A_PROMPT = (
23    "老修理工的手稳住了黄铜鸟。它的玻璃眼睛闪烁亮起， "
24    "翅膀钢板一片接一片咔哒打开。他俯身低语，靠近麦克风， "
25    ""让我看看你是否还记得天空。" 缓慢的50mm推进，灯光斜照在黄铜上， "
26    "雨滴敲击窗户，煤炉噼啪作响，在他声音下传来微小的伺服电机咔哒声。 "
27    "温暖的琥珀色主光，青色窗户补光。无屏幕文字。"
28)
29
30shot_a = create_task({
31    "model": "MiniMax-H3",
32    "resolution": "2K",
33    "duration": 8,
34    # 此处故意不写 "ratio"：图生视频从第一帧获取画面比例
35    "content": [
36        {"type": "text", "text": SHOT_A_PROMPT},
37        {"type": "image_url", "role": "first_frame",
38         "image_url": {"url": FIRST_FRAME_URL}},
39    ],
40})
41print("镜头 A 任务:", shot_a)
42

以下就是该提示词和第一帧作为任务运行的样子，这样你可以从另一侧看到健康的提交是什么样的：

Atlas Cloud 上的 MiniMax H3 图生视频游乐场，加载了作坊第一帧，输出面板中是渲染的片段

MiniMax H3 图生视频：左侧加载了第一帧，右侧 OUTPUT 中是完成的 2K 片段。注意 Aspect Ratio 字段固定为 adaptive，以及 2K 8 秒的 $1.12 报价。

第 3 步：轮询它，并处理所有五种 MiniMax H3 状态

这是每个人都会弄错的循环，所以值得完整写出来。四条规则：退避而非猛打，限制总等待时间，将 succeeded 视为“立即下载”，遇到不在枚举中的任何状态就抛出异常。

pythonCopy
1TERMINAL_OK   = {"succeeded"}
2TERMINAL_BAD  = {"failed", "cancelled"}
3IN_FLIGHT     = {"queued", "running"}
4
5def poll(task_id: str, timeout_s: int = 900) -> dict:
6    delay, deadline = 3.0, time.time() + timeout_s
7    while time.time() < deadline:
8        r = requests.get(f"{BASE}/v2/query/video_generation/{task_id}",
9                         headers=HEADERS, timeout=30)
10        r.raise_for_status()
11        task = r.json()["task"]
12        status = task["status"]
13
14        if status in TERMINAL_OK:
15            return task                                  # content.url 现在就可用
16        if status in TERMINAL_BAD:
17            raise RuntimeError(f"{status}: {json.dumps(r.json())[:400]}")
18        if status not in IN_FLIGHT:
19            # 一个不在枚举中的状态。不要落入“继续等待”的陷阱。
20            raise RuntimeError(f"未知状态 {status!r} -- 请阅读变更日志")
21
22        print(f"  {status} ... 下次检查在 {delay:.0f}s 后")
23        time.sleep(delay)
24        delay = min(delay * 1.5, 15.0)                    # 3s -> 15s 上限
25    raise TimeoutError(f"{task_id} 在 {timeout_s}s 后仍未终止")
26

其中有三个地方是故意的：

status not in IN_FLIGHT 抛出异常而不是继续。如果下个季度 MiniMax 添加了第六个状态，你希望听到一声巨响，而不是一个等待永远不会到来的词的循环。这一行就是有缺陷的教程和本教程之间的区别。

failed 不重试。渲染失败通常意味着提示词触发了过滤器或负载中存在不良组合，再次发送相同的负载只会以全价获得相同的失败。记录日志，查看它，然后决定。

退避从 3 秒开始，最终达到 15 秒。H3 在 2K 下需要几分钟，而不是几秒。每秒轮询一次只会消耗你在查询端点上的速率限制。

第 4 步：在 URL 过期前下载

一旦 succeeded 到达，立即将文件流式写入磁盘。content.url 中的 URL 明确是一个有时限的链接：“及时下载或存储它；过期后再次查询以获取新的 URL”（MiniMax API 参考，2026 年 8 月）。它不是一个你可以放入数据库然后忘记的 CDN 路径。

后半部分是个好消息，也是你第二天早上遇到 404 的答案。渲染没有消失。再次查询相同的 task_id 你会获得一个新的 URL，在创建后的 7 天内有效。

pythonCopy
1def download(url: str, path: str) -> str:
2    with requests.get(url, stream=True, timeout=300) as r:
3        r.raise_for_status()
4        with open(path, "wb") as f:
5            for chunk in r.iter_content(1 << 20):
6                f.write(chunk)
7    return path
8
9def refresh_url(task_id: str) -> str:
10    """链接失效了？渲染没问题。在 7 天窗口内再次询问。"""
11    r = requests.get(f"{BASE}/v2/query/video_generation/{task_id}",
12                     headers=HEADERS, timeout=30)
13    r.raise_for_status()
14    return r.json()["task"]["content"]["url"]
15
16task = poll(shot_a)
17download(task["content"]["url"], "shot-a.mp4")
18

镜头 A 返回的结果，旁边是它起始的静态图像：

并排：左侧是生成的第一个帧，右侧是完成的 MiniMax H3 片段中的一帧，显示鸟的翅膀钢板打开，眼睛发光

左侧：第 1 步中 GPT Image 2 的静态图像，完全按提交时显示。右侧：从 H3 返回的 2K 片段中提取的一帧。相同的场景，相同的光线，翅膀钢板和眼睛是移动的部分。

第 5 步：使用 MiniMax H3 文生视频的镜头 B，其中 ratio 是必需的

没有天空的源帧，所以镜头 B 是纯文本。这翻转了 ratio 规则，从“忽略”变为“必需”：对于纯文本提示词，ratio 是必需的，并且不能是 adaptive（MiniMax API 参考，2026 年 8 月）。漏掉它或发送 adaptive，你会立即收到 400，在渲染开始之前。

模型：minimax/h3/text-to-video。设置：2K，时长 6，比例 16:9。

textCopy
1黄铜鸟冲破半开的作坊天窗，飞入一个雨洗过的傍晚天空，翅膀在齿轮的嗡嗡声中拍打，水珠从金属羽毛上飞溅，它爬升经过湿漉漉的石板屋顶，朝向一片金色云彩的间隙。摄像机在其身后向上摇摄，24mm，低角度夕阳的逆光轮廓。声音：翅膀伺服电机嗡嗡作响，风渐起，远处教堂钟声，雨声渐弱。无文字。
2

pythonCopy
1shot_b = create_task({
2    "model": "MiniMax-H3",
3    "resolution": "2K",
4    "duration": 6,
5    "ratio": "16:9",          # 此处必需。省略它或传递 "adaptive" -> 400
6    "content": [{"type": "text", "text": SHOT_B_PROMPT}],
7})
8download(poll(shot_b)["content"]["url"], "shot-b.mp4")
9

Atlas Cloud 上的 MiniMax H3 文生视频游乐场，带有鸟起飞提示词和输出面板中的完成片段

MiniMax H3 文生视频，镜头 B 的提示词，Aspect Ratio 明确设置为 16:9。此运行使用了页面的默认 8 秒，而非上述负载中的 6 秒。

第 6 步：使用回调跳过轮询，并在 3 秒内返回挑战

如果你宁愿被通知而不是主动询问，在 create 调用时传递 callback_url。只有一个陷阱，它在 API 参考的一个括号中记录，并且是自托管回调失败的最常见方式。

在 MiniMax 向您推送任何内容之前，它会发送一个包含 challenge 字段的验证请求，并且“您必须在 3 秒内返回不变的 challenge 以完成验证”（MiniMax API 参考，2026 年 8 月）。错过它，哪都不会有错误。你的 create 调用继续成功，你的渲染继续完成，而你永远不会收到推送。日志中没有任何内容说明原因。

十二行 FastAPI 代码，其中的顺序是关键：

pythonCopy
1from fastapi import FastAPI, Request
2
3app = FastAPI()
4
5@app.post("/minimax/callback")
6async def callback(req: Request):
7    body = await req.json()
8    if "challenge" in body:                 # 验证握手，首先回答它
9        return {"challenge": body["challenge"]}   # 不变，同步，无认证门控
10    task_id = body.get("task_id")
11    status  = body.get("status")
12    enqueue(task_id, status)                # 真正通知：移交，快速返回
13    return {"ok": True}
14

导致它失败的错误，按我见过的频率排序：

• 挑战请求经过你的认证中间件，收到 401 或重定向。验证根据定义是未认证的。将路径加入白名单。
• 处理程序将挑战推入队列并异步回答。太晚了。该回复必须在该请求的响应体中。
• 值被重新序列化、修剪或包装。逐字节返回它。
• 你通过隧道在无服务器开发服务器上测试，单冷启动就超过 3 秒。先预热它，或者对照一个已在运行的进程进行验证。

顺便说一句，轮询完全没问题。如果你每小时只有少量任务，第 3 步中的循环代码更少，更不容易出错。当你有许多任务且不想为每个任务设置一个轮询器时，回调才值得。

第 7 步：将两个镜头拼接成一部电影

两个镜头都返回为 2560x1440 h264，24fps，AAC 立体声音频，32kHz。相同的容器，相同的一切，因此这是流复制而非重新编码。没有质量损失，无需等待。

一个值得预期的小意外：要求 6 秒得到了一个 6.58 秒的文件。时长与你要求的值接近，但并非精确到帧，因此两个镜头加起来是 14.62 秒而非整洁的 14 秒。

bashCopy
1printf "file 'shot-a.mp4'\nfile 'shot-b.mp4'\n" > list.txt
2ffmpeg -f concat -safe 0 -i list.txt -c copy brass-bird-two-shot.mp4
3

那个输出就是本文顶部的视频。如果 -c copy 报错，说明你的两个镜头分辨率或帧率不同，这在 H3 上意味着你在调用之间更改了 resolution。匹配它们，或者去掉 -c copy 并接受一次重新编码。

值得借鉴的 MiniMax H3 教程变体

在以上循环正常工作后，有五件事值得一试，大致按省钱程度排序。

以 768P 草稿，以 2K 完成。 两个层级是同一模型，768P 每秒成本约低 29%。渲染你的候选片段，短且便宜，观看它们，然后仅对获胜者使用相同提示词以 2K 重新运行。这是镜头列表中大部分节省所在。实际上你需要哪个层级用于交付是另一个争论，我在 768P vs 2K 中讨论过。

时长是 4 到 15 之间的任意整数。 不是一组预设。如果动作在 7 秒时结束，就请求 7 秒，停止为 8 秒付费。

首帧加末帧。 发送第二个图像项，role: "last_frame"，H3 会构建它们之间的过渡。适用于你已经艺术指导的镜头之间的交接。

参考视频以保持连续性。 role: "reference_image" 在镜头间保持角色一致，而不是每次生成重新调整他们的面部。还有一个匹配的 reference_audio 角色，参考片段窗口为 2 到 15 秒，用于保持声音一致。参见 参考视频。

纵向说话头。 ratio: "9:16" 配合提示词中的对话行是目前该模型用量最大的用法，因为音频来自同一轮，嘴唇匹配无需单独的唇形同步步骤。

提示词技巧是与异步管道不同的技能，如果你的镜头技术上干净但视觉上平淡，问题就在本文的上游。从 H3 提示词指南 开始。

本 MiniMax H3 教程的运行成本

顶部电影运行的实际账单，由运行按钮报价并于 2026 年 8 月 12 日验证。H3 按输出秒数计费，价格按分辨率分级：2K 任务报价 8 秒 $1.12，即每秒 $0.14，目录中的 $0.10 起始价格是 768P 层级。所有三个 H3 端点目前均为全价，无折扣。

值得注意的是，相同的两个镜头以 768P 草稿本分别为 $0.80 和 $0.60，而非 $1.12 和 $0.84，约 29% 折扣，对于你可以绝对判断镜头质量的素材而言。

两个容易以昂贵方式学会的账单细节。提交时被拒绝的请求不收费，因此缺失 ratio 的 400 是免费的。渲染出无用内容的请求不是免费的：如果任务达到 succeeded，你就会被收费，即使输出不是你想要的。这就是在 768P 草稿的真正理由。

每秒费率、768P 和 2K 的比较，以及费用在不同时长下的行为，都在本文的配套文章 MiniMax H3 API 定价 中详细说明。本文是代码，那篇是账单。

发布前的归属与地域限制

在将其公开发布之前，有两件事需要检查。MiniMax 的 API 条款中包含一项有条件辩护义务，涵盖针对 API 输出的专利和版权索赔，该义务不扩展到商标或肖像，因此提示词中的可识别标志或真实人物仍是你的问题。另外，H3 的开放权重许可证包含一项排他性地域条款，该条款约束下载的权重及其输出，而非托管 API，其条款指定了你可以选择的美国服务区域。阅读你实际签署的任何合同。并在你的 UI 中将 H3 输出标记为 H3 输出。

MiniMax H3 教程常见问题

MiniMax H3 任务状态有哪些？有 expired 状态吗？

五个：queued、running、succeeded、failed、cancelled。没有 expired 状态。有两样东西确实会过期并常被混淆：content.url 中的下载 URL 有时限，任务记录本身也只可查询最近 7 天。

我是否必须使用回调，还是轮询对 MiniMax H3 来说足够了？

轮询足够了，代码更少。当你同时有足够多的任务，使每个任务设一个轮询器显得愚蠢时，才使用回调。如果使用回调，端点必须在 3 秒内同步地、在任何认证中间件之前，原样返回 challenge 字段。失败的握手不会产生任何错误消息，只会永久沉默。

为什么我的 MiniMax H3 文生视频请求返回 400，提示“ratio is required and cannot be adaptive”？

因为你处于纯文本模式，没有第一帧来推断画面比例。传递一个明确的值：21:9、16:9、4:3、1:1、3:4 或 9:16。同样的规则也解释了为什么 ratio 在图生视频中看起来什么都不做，那里第一帧决定画面比例，你传入的任何 ratio 都会被忽略。

我可以同时运行多少个 MiniMax H3 任务？

文档限制是基于连接的：免费层 2 个并发任务，付费层 15 个。超过限制你会立即收到 429 而非队列槽位，因此限制你自己的进行中数量。路由网关有时能吸收更多，我曾有 20 个并发任务全部完成，但也在另一天在相同设置下遇到 429。不要构建一个假设更高数字的调度器。

我的 MiniMax H3 视频 URL 一天后返回 404。渲染消失了吗？

没有。URL 过期了，渲染没有。再次查询相同的 task_id，响应会携带一个新的 URL，在 7 天的查询窗口内任何时间均可。7 天后任务记录本身不再可查询，这就是为什么第 2 步在做任何其他事情之前先持久化 task_id。

我搜索了“hailuo ai video generator how to use”然后来到了一个 MiniMax H3 教程。我来对地方了吗？

是的。Hailuo 是消费者应用，H3 是 API 使用的模型名称。同一引擎。如果你想要一个片段，使用上面工作流程部分中的游乐场路径，无需代码。如果你想要十个变体或一个从另一个模型输入的首帧，七个步骤就是为你准备的。