博客

教程

如何通过 HiAPI API 调用 minimax-h3-max-turbo 文生视频

2026年11月12日
封面图:深石油蓝与青绿色调的平面多面矿物截面,宛如印刷的宝石学图谱,置于深色背景之上。
模型
minimax-h3-max-turbo
本页内容

该端点的功能与适用场景

minimax-h3-max-turbo/text-to-video 是通过 HiAPI API 暴露的文生视频模型端点。你发送一段描述目标场景的文本提示词,加上少量用于控制输出形态的参数,HiAPI 就会返回生成的视频。当你有文字描述而没有源素材时,这个模型非常合适:营销短片、社交媒体转场镜头、分镜预览、应用背景循环视频,或同一创意概念的批量变体生成。

在写代码之前,有几项特性值得注意:

  • 它是生成端点,不是模板。 输出只在结构上可预期(你会拿到一个视频),内容本身并不可预期。请把每次任务都视为一次全新渲染,并围绕可复用性来设计提示词。
  • 它是异步的。 提交任务的调用不会直接返回成品视频字节。你会先拿到一个任务句柄,然后轮询结果。任何假设同步响应的集成方式都会在第一次超时时失败。
  • 输出由请求参数决定。 时长和分辨率会改变渲染成本与实际耗时,因此你选择的参数同时也是延迟和预算决策。
  • 不需要源媒体。 你无需上传视频或图片;提示词和参数就是全部输入面。

什么时候该用别的方案?如果你已有素材,想要重风格化或延展,这不是合适的端点。如果你需要对镜头运动或精确构图做帧级控制,文本提示词会显得过于宽松。而如果你只需要一张静态图片,文生图端点更便宜也更快。当提示词足以作为镜头规格时,就使用 minimax-h3-max-turbo/text-to-video。

本指南的其余部分将依次介绍鉴权、可运行的 curl 调用、等效的 Python 调用、任务生命周期、关键参数、你将会遇到的错误,以及上线前的加固步骤。

前提条件与鉴权

首次请求之前,你需要准备三样东西:

  1. HiAPI 账户的 API 密钥。 请把它当作机密:从环境变量加载,绝不提交到代码库,一旦泄露立即轮换。
  2. HiAPI 基础 URL。 本指南中的所有调用都发往同一个基础主机;模型由路径段选择,而不是每个模型使用不同域名。
  3. HTTP 客户端。 冒烟测试用 curl,服务代码用任意标准库或 HTTP 客户端。

密钥的传递方式

HiAPI 通过 Authorization 请求头中的 bearer token 对请求进行鉴权。形式始终一致:

export HIAPI_API_KEY="your_api_key_here"
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

两个习惯能省下大量调试时间:

  • 请求头拼写必须精确。 Authorization 中 A 大写,Bearer 后跟一个空格,然后是密钥。少一个空格是神秘 401 最常见的原因。
  • 始终发送 Content-Type: application/json。 期望 JSON 的服务器会拒绝或错误解析未携带该头的请求体,而你收到的错误往往说某个字段缺失,而不是真正的原因。

先验证再开发

不要一上来就用视频端点。先做一次便宜、快速的调用,确认密钥和基础 URL 能正确解析,然后再继续。如果这个健全性检查失败,下游一切都不会工作,而你会在错误的层次上调试。把密钥放在代码库中的一个地方——一个小的客户端模块——这样以后轮换只需改一行。

可运行的 curl 请求

提交调用将提示词和参数作为 JSON 请求体发送到模型路径。以下是最小可运行调用:

curl -sS -X POST "$HIAPI_BASE_URL/minimax-h3-max-turbo/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "日出时分,缓慢的空中推镜掠过雾气弥漫的松林,柔和的体积光,电影感",
    "duration": 5,
    "resolution": "720p"
  }'

各部分的作用:

  • -X POST —— 生成任务通过 POST 创建。
  • URL —— 基础主机加上 minimax-h3-max-turbo/text-to-video 路径。把基础主机放在变量中,这样测试和生产可以指向同一代码路径。
  • Authorization —— 上一节所述的 bearer token。
  • Content-Type —— 声明 JSON 请求体。
  • prompt —— 唯一必需的创意输入。请按镜头描述来写:主体、镜头行为、光照和氛围。简短的名词短语会产生含糊的结果;一两句具体视觉方向的句子效果要好得多。
  • duration 与 resolution —— 控制输出形态的参数,下文有专门章节介绍。

使用 -sS 让 curl 静默但仍打印错误,在探索阶段用美化打印工具输出响应。响应是包含任务标识符的 JSON;请保存它,因为需要用它来轮询已完成的视频。不要期望这个响应里包含视频字节。

如果调试时想看清究竟发送了什么,可以加 -v 获取详细输出,但在分享日志前要去掉,因为详细输出可能包含请求头。

等效的 Python 请求

Python 版本是同一个请求,只是从环境加载密钥并解析响应。以下是一个小型可复用客户端:

import os
import time
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

MODEL_PATH = "/minimax-h3-max-turbo/text-to-video"


def submit_video(prompt: str, duration: int = 5, resolution: str = "720p") -> dict:
    payload = {"prompt": prompt, "duration": duration, "resolution": resolution}
    resp = requests.post(
        f"{BASE_URL}{MODEL_PATH}",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    job = submit_video(
        "日出时分,缓慢的空中推镜掠过雾气弥漫的松林,柔和的体积光,电影感"
    )
    print(job)

适配时的注意事项:

  • json=payload 同时设置请求体和内容类型;不要再手动序列化。
  • timeout=30 限定提交调用的时间。提交很快,渲染不快,这就是这里超时设得短、由轮询负责等待的原因。
  • raise_for_status() 将非 2xx 响应转为异常,让鉴权和校验失败立即暴露,而不是悄悄返回一个错误响应体、让你之后误当作任务来解析。
  • 将解析后的 JSON 作为字典返回,在调用处提取任务标识符。这样辅助函数保持通用,而编排代码决定如何处置它。

如果你使用的是异步栈,同样的形态适用于你选择的 HTTP 客户端:构建一次请求头,POST 请求体,检查状态,返回解析后的响应体。

处理异步任务生命周期

生成需要时间,因此端点分为提交和轮询。生命周期始终是:提交,收到任务标识符,轮询任务直到报告终态,然后获取输出。

提交

发送前面描述的 POST,并从响应中读取任务标识符。立即记录它,并与你自己的请求 ID 关联,这样之后轮询失败时可以追溯回原始提示词。

带退避的轮询

不要用紧凑循环轮询。从较短间隔开始,然后退避:

def wait_for_job(job_id: str, max_wait: int = 600) -> dict:
    deadline = time.time() + max_wait
    interval = 2.0
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}{MODEL_PATH}/{job_id}",
            headers=HEADERS,
            timeout=30,
        )
        resp.raise_for_status()
        job = resp.json()
        status = job.get("status")
        if status in ("succeeded", "failed"):
            return job
        time.sleep(interval)
        interval = min(interval * 1.5, 15.0)
    raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")

三个细节让这段代码可靠。第一,截止时间:始终要最终放弃并抛出超时,而不是永远轮询。第二,有上限的退避:从几秒开始,逐步倍增,并封顶间隔,这样既能持续取得进展,又不会频繁冲击 API。第三,终态处理:只把成功和失败视为终态,并返回任务对象以便调用方分支处理。

获取结果

一旦任务报告成功,响应会携带成品视频的位置。尽快下载或流式传输到你自己的存储,并将 URL 与任务 ID 一起记录。不要假设链接永久有效,也不要在每次轮询迭代中都获取视频。轮询任务状态,然后在成功时获取一次。

时长与分辨率参数

两个请求参数决定输出,同时也决定渲染时间和调用成本。

duration

生成片段的长度。片段越长,渲染时间按比例增加,这意味着更长的轮询窗口和更大的客户端超时触发概率。实用建议:

  • 让时长匹配用例。 社交媒体转场镜头很短;背景循环只需长到能可接受地循环即可。生成比实际展示更长的内容是纯浪费。
  • 迭代时从小处开始。 在较短的时长下调整提示词,然后用最终长度重新渲染获胜的提示词。
  • 记住成本随输出规模增长。 计费按输出长度计算,因此时长既是创意杠杆,也是预算杠杆。

resolution

输出的空间质量。更高分辨率带来更多细节,但消耗更多渲染时间和更多费用。建议:

  • 按交付场景选择,而不是按规格表。 如果视频会出现在信息流或小播放器中,生成高于该场景的分辨率不会带来任何收益。
  • 低分辨率迭代,高分辨率出片。 在仍在修改提示词时用较低分辨率预览,然后用交付分辨率重新提交已批准的提示词。
  • 更高设置意味着更久等待。 轮询截止时间要按你允许的最大组合来设置,而不是最小组合。

将这两个值放在同一个配置对象中,而不是分散在代码各处,这样从预览切换到生产的改动就是一次有意且可见的编辑,而不是被遗忘的字面量。

调试常见错误

大多数失败可归为四类。在改代码之前,先将症状与类别对应起来。

鉴权失败

401 表示 HiAPI 不接受你的凭据。按顺序检查:Authorization 请求头存在且拼写正确;Bearer 之后恰好一个空格;密钥是当前有效的,且不是来自其他项目;环境变量确实已加载(粘贴密钥时末尾带换行符是经典问题)。通过回显变量的长度而非密钥本身来确认。

校验失败

非 401 的 4xx 通常意味着请求体有误。Content-Type 缺失或不是 application/json;prompt 缺失或为空;duration 或 resolution 超出允许集合。按字面阅读错误消息;它通常会指出有问题的字段。用 curl 版本复现,因为那里没有库层遮挡请求体。

超时

有两种不同的超时。提交超时意味着 POST 本身未返回,通常指向网络路径或过于激进的客户端超时。轮询超时意味着任务在你的截止时间之前未达到终态;要么渲染确实需要更久,要么你的截止时间是按预览设置而非生产设置来定的。修复后者应针对大时长和大分辨率提高 max_wait,而不是缩短轮询间隔。

轮询错误

更隐蔽的那些。不睡眠地轮询浪费配额并招致限流;以固定短间隔轮询也有同样效果。轮询错误的任务 ID,通常是因为你在多次提交之间复用了变量。把中间状态当作错误。以及在每次迭代时获取视频 URL 而不是在成功时获取一次。记录任务 ID 和每个观察到的状态;序列会立刻告诉你命中了其中哪一种。

上线前的生产检查清单

从可工作的脚本迈向无人值守运行的服务,意味着围绕同一个请求增加几层。

  • 带抖动的重试。 对瞬时网络错误和 5xx 响应进行带指数退避和随机化的重试。绝不要重试校验错误;它们会以同样方式失败并消耗配额。
  • 处处有界超时。 提交用短超时,轮询用较长的截止时间(按你允许的最大时长和分辨率设置),视频下载也要有超时。
  • 结构化日志。 记录你的请求 ID、任务 ID、每个观察到的状态转换和最终结果,但不要记录 API 密钥或完整请求头。当凌晨三点出问题时,这份日志是你唯一的证据。
  • 你的层做幂等。 维护从你自己的请求 ID 到任务 ID 的映射,这样客户端重试不会悄悄产生第二次渲染。
  • 成本控制。 计费按输出长度计算,因此要设置服务接受的最大时长和分辨率上限,并在人工或规则批准最终渲染之前,将提示词预览保持在较低设置。
  • 密钥卫生。 从密钥存储加载密钥,按计划轮换,测试和生产使用不同密钥,这样泄露的测试密钥无法消耗生产预算。
  • 结果归属。 任务一旦成功,立即将成品视频复制到你控制的存储中,并将交付 URL 视为临时链接。

把这些落实到位,端点就会成为可预测的依赖,而不是意外的来源。先用上面的 curl 请求确认凭据,然后把 Python 客户端引入你的服务,并用本清单中的检查包装它。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档