教程
如何通过 HiAPI API 使用 minimax-h3-max-turbo/image-to-video:curl、Python 与可用的请求示例
本页内容
该端点做什么,以及何时使用
minimax-h3-max-turbo/image-to-video 接收一张源图加一段文本提示词,返回以该图为起点的短视频。图像充当第一帧(或视觉锚点),因此输出会继承其构图、色调和主体身份。随后提示词描述接下来应该发生什么——镜头运动、主体动作、氛围。
何时选择它而非文生视频
当您没有参考视觉、希望模型自行创造一切时,文生视频是合适的工具。当第一帧本身就是重点时,图生视频才是正确选择:您已有一张已获批的产品图、一张分镜关键帧、一个角色设计或一张用户上传的照片,需要它动起来同时保持可辨识。具体而言,团队会在以下情况下使用该端点:
- 第一帧是合同要求。 市场团队需要精确的主图来开场,而不是一张相似的图。
- 跨片段一致性很重要。 复用同一张源图可以让角色或产品在一系列片段中保持稳定。
- 您正在让用户内容动起来。 终端用户上传的照片应该被动画化,而不是被重新想象。
- 您希望提示词范围更聚焦。 描述运动比从零描述整个场景更容易,因此提示词保持简短且可预测。
该端点是异步的:您提交任务,然后取回渲染好的视频。这种形态很适合队列驱动的后端,下文将详细介绍。如需完整参数面,请参见模型页面。
前提条件与请求结构
在调用端点之前,请确认您具备四项内容:
- 一个 API 密钥。 在您的 HiAPI 账户中创建,并以 bearer token 形式发送。请将其视为机密——切勿嵌入客户端代码。
- 基础 URL。 所有请求都发往 HiAPI 统一 API 主机;端点路径即模型标识符。
- 一张源图,可访问或可编码——要么是公开 HTTPS URL,要么是 base64 载荷,取决于请求 schema 接受哪种形式。
- 一个 HTTP 客户端——用于冒烟测试的
curl,以及用于真实集成的任意标准库或 Python 中的requests。
请求的组成部分
无论使用哪种语言,每次任务提交都包含相同的概念性部分:
- 模型 / 端点——
minimax-h3-max-turbo/image-to-video,属于请求路径的一部分,并在请求体中重复出现以保持清晰。 - 源图——第一帧。这是区分图生视频与文生视频的字段,也是最容易引发校验错误的字段。
- 提示词——运动与场景描述。只描述会变化的内容,而不是图像中已存在的内容。
- 可选的生成提示——时长和分辨率风格控制,如果端点提供这些。只发送 schema 文档中记录的参数;未知键是 4xx 响应的常见来源。
提交会返回任务标识符和状态。视频本身稍后通过第二次请求到达——这就是为什么下面的轮询部分与提交调用同样重要。
一个可用的 curl 请求
以下命令提交一个图生视频任务。运行前,请将占位符——尖括号中的大写标记——替换为您自己的值。
curl -X POST "https://api.hiapi.ai/v1/<ENDPOINT_PATH>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3-max-turbo/image-to-video",
"image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
"prompt": "Slow push-in on the product, soft studio light shifting across the surface, shallow depth of field."
}'
关于此命令的几点实用说明:
- 从环境变量读取密钥。
$HIAPI_API_KEY可以避免密钥进入 shell 历史记录,前提是您导出它而不是内联粘贴。 - 首次测试使用公开图片 URL。 这样可以排除 base64 编码因素,同时确认认证和连接正常工作。
- 保持 JSON 请求体小巧。
-d载荷就是整个请求;这里少一个逗号会产生令人困惑的 400,而不是清晰的 schema 错误。 - 给提示词加引号。 含标点符号的提示词会破坏未加引号的 shell 字符串。
响应是一个任务对象,而不是视频。从中捕获任务 ID——您将把该 ID 用于轮询请求。如果调用立即失败,请跳到故障排查部分;认证和载荷错误会在此步骤暴露,而不是稍后。
Python 中的同一请求
以下是使用 requests 的 Python 等效提交调用。它假设环境变量中已设置 HIAPI_API_KEY。
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1/<ENDPOINT_PATH>"
payload = {
"model": "minimax-h3-max-turbo/image-to-video",
"image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
"prompt": (
"Slow push-in on the product, soft studio light shifting "
"across the surface, shallow depth of field."
),
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
response.raise_for_status()
job = response.json()
print(job["id"], job.get("status"))
改编此片段时应保留的要点:
- 超时不是可选项。 提交很快,但 Web 请求处理器中挂起的 socket 会把您的 worker 一起拖垮。
- 解析前先
raise_for_status()。 它能把静默的 401 变成您可以实际记录的异常。 - 返回任务 ID,而不是响应。 在服务中,提交函数应返回标识符,以便单独的轮询器——或后台任务——负责等待。
- 将载荷保存在变量中。 调用成功后,把图片 URL 换成签名上传 URL 或 base64 字符串只需改一行。
这里刻意使用普通 HTTP 客户端而非封装库:请求形态就是契约,您应该能够在技术栈使用的任何语言中复现它。
准备图像与第一帧
大多数失败的图生视频任务都败在图像上,而不是提示词上。养成几个习惯可以避免这种情况。
格式与交付
使用标准、广泛支持的光栅格式——JPEG 或 PNG——并确保 URL 可公开获取,无需 cookie、不重定向到登录页、也不依赖提交后生成的过期签名。如果您的资源位于私有桶中,请生成一个生命周期明显长于任务预期运行时间的签名 URL。对于 base64 载荷,如果 schema 期望原始编码字节,请去掉 data-URI 前缀,并确保编码后的大小远在文档限制之内。
尺寸与构图
模型以固定输出尺寸渲染视频,因此源图会被适配。两个后果:
- 匹配您想要的宽高比。 将竖版人像照片送入横版渲染会被裁切或加黑边,主体可能偏离中心。
- 为运动留出余量。 如果提示词描述镜头推进或主体向上移动,请在源图中朝该方向留出空间。
保持第一帧完整
开场帧主要靠图像本身。将提示词写为对第一帧之后发生什么的指令:描述镜头行为、主体动作和光照变化。避免重新描述场景——当图像已经显示“白色地板上的红色椅子”时,重复描述往往会增加漂移而非保真度。如果结果偏离源图,先缩短提示词,再考虑更换图像。
不要假设存在未文档化的参数。如果您想要的控制项不在 schema 中,请通过提示词或图像准备来实现。
处理异步任务生命周期
图生视频任务不是同步的。模式是提交 → 轮询 → 取回,生产集成应显式实现全部三步。
1. 提交并持久化
提交请求并立即存储返回的任务 ID,最好与您自己的关联 ID、请求载荷哈希和时间戳一起存储。如果进程在提交与存储之间死亡,您就为一个无法取回的任务付了费。
2. 带退避的轮询
使用存储的 ID 轮询任务状态端点。视频渲染耗时明显长于图像生成,因此:
- 从适中的间隔开始——几秒钟——并随着任务时间增长而增加,而不是以固定速率猛击端点。
- 将总等待时间限制在适合任务的上限,然后将任务视为超时,并决定是否重试。
- 将终态视为终态:一旦任务报告成功或失败,就停止轮询。
import time
def wait_for_job(poll_fn, job_id, max_wait=600):
deadline = time.time() + max_wait
interval = 5
while time.time() < deadline:
job = poll_fn(job_id)
if job["status"] in ("succeeded", "failed"):
return job
time.sleep(interval)
interval = min(interval * 1.5, 30)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
3. 取回并存储输出
成功后,任务对象携带结果位置。及时下载视频并复制到您自己的存储——输出 URL 应视为临时资源,而不是您的永久资产库。将任务 ID 记录在存储文件旁边,以便支持人员将任何片段追溯回其请求。
对于重试,只重新轮询您已存储 ID 的任务;切勿盲目重新提交,否则会产生重复渲染和重复计费。
常见错误排查
认证失败(401 / 403)
首先检查 Authorization 头:Bearer 一词、一个空格、然后是密钥,且没有从复制密钥带来的尾随换行符。确认密钥处于活跃状态并属于您预期的账户。如果 curl 可用而 Python 不可用,请打印头部长度——空的环境变量会产生一个看似有效但无用的 token。
格式错误或不支持的图像载荷(400 / 422)
最常见的非认证失败。按顺序检查:
- 图片 URL 能正常解析,且不会重定向到 HTML 登录页。
- 格式为 JPEG 或 PNG,而不是 WebP、HEIC 或 PDF 缩略图。
- 编码或下载后的大小在文档限制内。
- Base64 载荷没有
data:前缀,也没有因换行产生的空白。 - 图像未损坏——在责怪 API 之前,先自己获取并打开它。
未知或无效参数
字段名拼写错误,或端点未暴露的参数,通常会返回指明该字段的校验错误。移除推测性参数,并从文档规定的最低要求重建。
速率限制(429)
指数退避,并遵守响应中的任何重试提示。不要在紧循环中重试;那会加深限制。如果您经常遇到,请通过队列批量提交,而不是从用户请求中内联触发。
任务超时与轮询卡住
如果任务在您的预算内从未达到终态,请记录任务 ID 和状态历史并停止轮询。持续超时通常表明提交时图像过大或异常,因此请重新查看图像准备部分。不要在未设置尝试上限的情况下自动重新提交。
上线前的生产检查清单
在该端点接近真实流量之前,请验证以下各项:
- 处处都有超时。 提交使用短超时,轮询设置总等待上限,重试尝试有硬上限。没有无界的
while True循环。 - 带退避的重试。 重试 429 和瞬态 5xx 响应;绝不重试校验错误——它们会以相同方式失败。
- 日志中有任务 ID。 为每个请求记录任务 ID、您的关联 ID 和最终状态。这是您能保留的最有用的调试产物。
- 输出存入您自己的存储。 将完成的视频从返回 URL 复制到持久存储,并保留源图引用以实现可复现性。
- 边缘图像校验。 在到达 API 之前拒绝错误格式和超大上传,让用户立即得到清晰错误,而不是几分钟后的异步失败。
- 成本意识。 生成按渲染视频的每个输出计费,因此请跟踪每个用户或功能的任务量和时长。查看当前定价面板,而不是把假设硬编码到代码或文档中。
- 金丝雀提示词。 在测试套件中保留一组已知良好的图像和提示词,并在任何集成变更后运行它,以确认请求契约仍然成立。
一旦正确处理异步生命周期——提交、持久化、轮询、存储——该端点就很直接。请从模型页面获取确切 schema,然后接入上述提交与轮询模式。