教程
如何通过 HiAPI API 使用 minimax-h3:curl、Python 与可运行的请求
本页内容
minimax-h3 集成端到端是什么样子
视频生成不是瞬时操作。minimax-h3 需要接受提示词或源图片,在 GPU 池上调度任务、编码帧并组装输出文件。整个过程根据时长和分辨率的不同,可能需要几秒到几分钟。如果 HiAPI 端点阻塞到文件就绪,你的 HTTP 客户端将全程占用一个打开的连接——在重试时很脆弱,对无服务器时间限制不友好,也无法在请求/响应式的 Web 处理器中运行。
因此,集成遵循先提交后轮询的形态,这是异步媒体 API 的标准模式:
- 提交。你
POST一个描述任务的 JSON 载荷(提示词、可选图片、时长、宽高比以及任何模型特定参数)。API 验证后立即返回任务标识符和初始状态。 - 轮询。你以较短的间隔用该标识符调用任务状态端点。状态会经历排队、处理中,然后成功或失败等状态。
- 获取。一旦状态进入终止态,响应会携带结果——通常是生成视频的可下载 URL。
这个模型带来三个后果,它们决定了本指南后续的所有内容:
- 任务 ID 是你唯一的句柄。持久化它。如果你丢失了它,就无法检索任务;只能重新提交并再次为工作付费。
- 你的代码有两个失败面,而不是一个。提交可能失败(认证、载荷格式错误),轮询也可能失败(超时、瞬时网络错误、任务终止失败)。分开处理它们。
- 轮询节奏是一个设计决策。太激进会浪费请求;太慢会让用户等待一个早已就绪的状态。
在本文中,所有调用都发往 HiAPI 统一 API。你需要从 HiAPI 账户获取 API 密钥,并在载荷中将模型引用为 minimax-h3。其余一切——认证头、基础 URL、轮询端点——在整个平台共享,因此你在这里学到的模式可以迁移到其他模型,而无需重构客户端。
有了这个心智模型,确认设置的最快方式是单个 curl 调用。
你的第一个可运行 curl 请求
在编写任何应用代码之前,确认你的密钥有效且能访问 API。一次性 curl 命令是区分认证问题和载荷问题的最廉价方式。
首先导出你的密钥,这样它就不会以字面形式落入 shell 历史记录:
export HIAPI_API_KEY="your-api-key-here"
然后提交一个最小的文本生成视频任务:
curl -sS -X POST "https://api.hiapi.ai/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3",
"prompt": "A slow aerial shot over a fog-covered pine forest at sunrise",
"duration": 5,
"aspect_ratio": "16:9"
}'
成功响应会返回一个 JSON 对象,包含任务标识符和状态。其结构大致如下:
{
"id": "task_abc123xyz",
"status": "queued",
"model": "minimax-h3",
"created_at": "2024-01-01T00:00:00Z"
}
注意此时还没有视频 URL。这是预期内的——任务只是被接受了。你实际响应中的字段名可能与上图略有不同;要读取响应体而不是假设,并在开发期间记录整个内容。
请求的每个部分做什么
- URL 指向 HiAPI 平台上的视频生成资源。所有模型调用共享这个基础,这就是为什么切换模型只是更改载荷而不是重写代码。
Authorization: Bearer携带你的 API 密钥。这是最常见的失败来源,因此出问题时首先验证它。Content-Type: application/json是必需的。没有它,服务器可能拒绝或错误解析请求体。model显式选择 minimax-h3。永远不要省略它——平台基于此值进行路由。prompt是创意指令。要具体说明主体、摄像机运动和光照;模糊的提示词会产生模糊的视频。duration和aspect_ratio约束输出。保持它们在模型支持的范围内;超出范围的值是载荷验证错误,不是服务器故障。
确认任务存在
提交后立即获取一次任务,以证明 ID 有效:
curl -sS "https://api.hiapi.ai/v1/tasks/task_abc123xyz" \
-H "Authorization: Bearer $HIAPI_API_KEY"
将 task_abc123xyz 替换为提交响应中的 ID。如果这返回了状态,那么你的密钥、端点、任务句柄都正确——你就可以进入 Python 了。
现在值得养成两个习惯:使用 -sS 运行 curl,让错误浮现而不是被静默吞掉,并且始终给 URL 加引号。JSON 载荷中意外的 shell 展开是一个调试陷阱,花费的时间比引号本身多得多。
在 Python 中构建相同的请求
curl 调用证明了契约;Python 是你构建可复用内容的地方。不要直接跳到轮询循环,而是从一个小的客户端类开始,将提交和结果检索作为两个清晰的方法处理。这种分离将异步逻辑排除在你的传输层之外。
使用 requests(如果你偏好异步,则使用 httpx);两种方式的形态相同。
import os
import time
import requests
BASE_URL = "https://api.hiapi.ai/v1"
class MiniMaxH3Client:
def __init__(self, api_key: str | None = None):
self.api_key = api_key or os.environ["HIAPI_API_KEY"]
self.session = requests.Session()
self.session.headers.update({
"Authorization": f"Bearer {self.api_key}",
"Content-Type": "application/json",
})
def submit(self, prompt: str, duration: int = 5,
aspect_ratio: str = "16:9", **extra) -> str:
payload = {
"model": "minimax-h3",
"prompt": prompt,
"duration": duration,
"aspect_ratio": aspect_ratio,
**extra,
}
resp = self.session.post(
f"{BASE_URL}/video/generations",
json=payload,
timeout=30,
)
resp.raise_for_status()
data = resp.json()
return data["id"]
这里有几个刻意的选择值得指出。
使用 session,而不是裸 requests。复用 requests.Session 可以在提交和轮询调用之间保持连接活跃,当你反复轮询同一主机时这很重要。它还集中管理头,因此认证头只定义一次。
提交时设置硬超时。对于一个几乎应立即返回的请求,三十秒很宽裕。没有超时,网络抖动会让你的进程无限挂起。永远不要在任何远程 API 调用上不设置 timeout。
解析前调用 raise_for_status()。非 2xx 响应的响应体形状通常与成功响应不同。先检查状态码意味着你的错误处理读取的是格式良好的错误消息,而不是在缺失 id 键时崩溃。
**extra 透传。模型特定选项会演进。透传额外的关键字参数让你可以试验新参数,而无需每次都编辑方法签名。
使用它
client = MiniMaxH3Client()
task_id = client.submit(
"A slow aerial shot over a fog-covered pine forest at sunrise"
)
print(f"submitted: {task_id}")
这就是整个提交路径。客户端返回一个字符串——任务句柄——没有别的。抵制让 submit 同时等待结果的冲动。将提交和等待混入一个方法会使重试变得模糊:失败时,你无法判断任务是否已创建,因此有重复生成的风险。保持它们分离,由调用者决定策略。
轮询结果而不轰炸 API
轮询是最容易被粗心编写的部分。一个没有延迟的朴素 while True 循环会向一个需要两分钟的任务发出数百个请求,并且在任务已经失败后还会继续这样做。
一个正确的轮询循环有四项职责:检查状态、等待、在终止态停止、最终放弃。
TERMINAL = {"succeeded", "failed", "cancelled"}
def wait_for(self, task_id: str, interval: float = 3.0,
max_wait: float = 600.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
resp = self.session.get(f"{BASE_URL}/tasks/{task_id}", timeout=30)
resp.raise_for_status()
data = resp.json()
status = data.get("status", "unknown")
if status in TERMINAL:
return data
time.sleep(interval)
raise TimeoutError(f"task {task_id} did not finish in {max_wait}s")
选择间隔
对于视频生成,固定几秒是一个合理的默认值。任务不会在最初几秒内完成——模型加载和帧编码都需要真实时间——因此每 200 毫秒轮询一次除了负载之外什么也得不到。如果你想同时礼貌且高效,使用带上限的指数退避:从一两秒开始,每轮乘以大约 1.5,直到达到五或十秒,然后保持在那里。早期轮询能快速捕获快速失败;后期轮询在长时间渲染期间保持低成本。
正确停止
将任何未识别的状态视为非终止态并继续等待——但只到某个限制。两个停止条件很重要:
- 终止状态。成功时立即返回。失败时,从响应中浮现错误消息,而不是返回空结果;原因对你的日志很重要。
- 实际时间预算。使用单调时钟,而不是墙钟时间,这样系统时钟调整不会让你的循环提前退出或永远运行。选择一个舒适地高于你所选时长和分辨率的最长现实任务的上限,并将达到它视为需要告警的操作错误。
返回结果
当状态为终止成功时,响应携带生成视频的 URL。及时下载它——结果 URL 通常带有过期时间——如果你需要持久访问,将其存储在你自己的对象存储中。不要将供应商 URL 直接传递给最终用户并假设它会永远存在。
还有一个实用提示:在调试级别记录每次轮询的任务 ID、状态和经过时间,在信息级别记录终止结果。当任务耗时超过预期时,该时间线是五分钟诊断与一小时猜测之间的区别。
文本生成视频与图片生成视频的请求形态
两种生成模式共享大部分载荷。不同之处在于创意输入,而这种差异对你应预期何种失败有下游影响。
文本生成视频
这是前面章节展示的形态:提示词加输出约束。模型发明一切——构图、运动、光照和主体细节。你的载荷携带:
model:minimax-h3prompt:场景描述duration、aspect_ratio以及任何其他输出控制
由于没有任何锚定,提示词质量主导结果。描述摄像机行为(「缓慢推进」、「静态三脚架镜头」)和光照(「黄金时刻逆光」),而不是堆砌关于质量的形容词。模糊的顶级形容词作用很小;具体的物理描述作用很大。
图片生成视频
图片生成视频变体在同一请求中添加源图片引用。通常你在提示词旁边的图片字段中提供图片 URL 或上传的资源标识符,模型从该起始帧开始动画化。
client.submit(
"Gentle wind moves the hair, subtle camera push forward",
duration=5,
image_url="https://example.com/portraits/source.jpg",
)
提示词现在扮演不同的角色:它指导运动和摄像机,而不是内容,因为视觉内容已由图片固定。编写完整的场景描述通常适得其反——模型无法添加画面中不存在的位置。保持运动提示词简短且具体。
查阅请求参考以了解图片模式中确切的字段名和接受的图片格式,以及两种模式中时长和宽高比的有效范围。这些约束正是驱动载荷验证错误的约束,因此读一次可以节省一轮后续调试。
一个实用的经验法则
当你需要新颖场景时选择文本生成视频——B-roll、情绪片段、概念可视化。当一致性重要时选择图片生成视频:为产品照片添加动画、让角色肖像活起来,或将故事板帧转为运动镜头。模式是载荷差异,不是集成差异,因此一个客户端类只需接受可选图片参数即可服务两者。
调试常见错误
当 minimax-h3 调用出错时,原因几乎总是在四个地方之一。按此顺序排查。
1. 认证
症状:401 或 403 响应,或错误体声明凭据无效。
- 确认
Authorization头存在且格式为Bearer <key>,中间有一个空格。 - 检查环境变量确实持有值——粘贴到环境变量中的尾随换行符会以日志中不可见的方式破坏头。
- 验证密钥属于你期望的同一 HiAPI 项目且未被轮换。
最快的测试:重新运行之前的原始 curl。如果 curl 有效而 Python 无效,bug 在你的客户端,而不是你的账户。
2. 格式错误的载荷
症状:400 或 422 响应,或命名参数的验证消息。
- 确认
Content-Type: application/json且请求体是有效 JSON——多余的尾随逗号是经典罪魁祸首。 - 检查
model正好是minimax-h3。 - 确认
duration和aspect_ratio在模型支持的范围内。 - 在图片模式中,确认图片引用可访问且为接受的格式。
字面阅读错误消息。验证错误通常命名违规字段;开发者常常略过这一点,开始重写载荷中不相关的部分。
3. 轮询永不完成
症状:状态在合理时长之后仍为排队或处理中,或永远循环。
- 记录完整状态响应——状态值可能不是你的代码假设的。
- 检查你读取的字段。如果你的终止集合检查
"completed",但 API 返回"succeeded",你的循环会永远运行。在开发早期打印一个原始响应。 - 确认任务 ID 被精确复制,没有截断或空白。
- 添加实际时间截止;没有上限的卡住循环是你代码的 bug,不是 API 的。
4. 超时和瞬时网络错误
症状:连接错误、读取超时,或提交或轮询时的 5xx 响应。
- 确保每次调用都传递显式
timeout——许多客户端的默认值是无,意味着挂起的套接字可以永远阻塞。 - 区分连接超时和读取超时;读取超时的提交可能实际上已创建任务。如果返回了请求 ID,从响应头记录它,并在盲目重新提交之前检查是否出现了任务。
- 对于轮询的 5xx,重试——任务可能没问题。对于提交的 5xx,验证没有创建任务以避免重复生成。
一个快速分诊习惯:在项目旁边保留一个草稿 curl 文件,提交和轮询命令从环境变量预填充。在应用代码之外重现任何 bug 只需几秒,并立即告诉你问题是传输还是逻辑。
使其生产就绪
可运行的脚本不是可运行的服务。视频任务足够慢,生产流量会重叠、重试,并偶尔以单次手动运行永远不会揭示的方式失败。四种模式承担了大部分重量。
带退避的重试——但只在安全的地方
重试策略取决于哪个调用失败:
- 轮询本质上可以安全重试。失败的状态检查没有副作用,因此使用带抖动的指数退避重试,限制在少数几次尝试。
- 提交不能盲目重试。超时并不意味着任务未被创建。在重新提交之前,检查该请求的任务是否已存在(如果可用,使用响应头中的请求 ID,或短的对账窗口)。或者,通过按载荷哈希缓存任务 ID 使你自己的提交幂等,这样重试的请求会返回现有任务而不是启动新的渲染。
- 模型级失败——终止状态
failed——通常不应使用相同载荷自动重试。相同输入倾向于以相同方式失败。记录它、告警,让人类或修改的提示词接手。
在每个退避睡眠中添加抖动。没有它,一批同步重试的 worker 会产生同步尖峰,使糟糕的情况更糟。
到处记录任务 ID
任务 ID 是你的系统与生成视频之间唯一持久的链接。提交成功的那一刻,使用结构化字段——task_id、模型、时长、提交时间戳——将其写入日志。当用户报告视频丢失时,按任务 ID 搜索可以在几秒内找到完整历史。还要记录终止状态和经过时间,这样你可以用数据而不是记忆回答「这通常需要多长时间」。
设置显式超时预算
从整个操作的总预算角度思考,而不仅仅是每个请求的超时。任务有三个阶段——提交、等待、下载——每个都需要边界。一个合理的结构:
- 提交和轮询请求的短超时,以便快速检测死连接。
- 轮询的总实际时间上限,按你支持的最长时长和分辨率设定并留有余量。
- 带流式写入的有界下载,这样大文件不会耗尽内存或挂起 worker。
当预算耗尽时,干净地使任务失败、释放并发槽位并报告清晰的错误。可预测的失败胜过挂起直到平台重启容器的请求。
将提交与消费分离
先提交后轮询的设计自然映射到队列架构:你的 Web 处理器提交并返回任务 ID,后台 worker 轮询并存储结果,客户端轮询你的状态端点。这将面向用户的延迟与渲染时间解耦,使并发限制易于执行,并意味着提交激增不会耗尽你的 Web 层线程池。
把这四点做对,minimax-h3 的异步形态就会与你配合而不是对抗你:任务被跟踪、重试是安全的、失败可见,且没有任何东西无限挂起。