博客

教程

如何通过 HiAPI API 使用 minimax-h3-max-turbo/image-to-video:curl、Python 与可用的请求示例

2026年11月17日
由陶土色与赭褐色构成的宽阔水平阶梯色带在暖沙色背景上层层下降,边缘呈平面印刷质感。
本页内容

该端点做什么,以及何时使用

minimax-h3-max-turbo/image-to-video 接收一张源图加一段文本提示词,返回以该图为起点的短视频。图像充当第一帧(或视觉锚点),因此输出会继承其构图、色调和主体身份。随后提示词描述接下来应该发生什么——镜头运动、主体动作、氛围。

何时选择它而非文生视频

当您没有参考视觉、希望模型自行创造一切时,文生视频是合适的工具。当第一帧本身就是重点时,图生视频才是正确选择:您已有一张已获批的产品图、一张分镜关键帧、一个角色设计或一张用户上传的照片,需要它动起来同时保持可辨识。具体而言,团队会在以下情况下使用该端点:

  • 第一帧是合同要求。 市场团队需要精确的主图来开场,而不是一张相似的图。
  • 跨片段一致性很重要。 复用同一张源图可以让角色或产品在一系列片段中保持稳定。
  • 您正在让用户内容动起来。 终端用户上传的照片应该被动画化,而不是被重新想象。
  • 您希望提示词范围更聚焦。 描述运动比从零描述整个场景更容易,因此提示词保持简短且可预测。

该端点是异步的:您提交任务,然后取回渲染好的视频。这种形态很适合队列驱动的后端,下文将详细介绍。如需完整参数面,请参见模型页面。

前提条件与请求结构

在调用端点之前,请确认您具备四项内容:

  1. 一个 API 密钥。 在您的 HiAPI 账户中创建,并以 bearer token 形式发送。请将其视为机密——切勿嵌入客户端代码。
  2. 基础 URL。 所有请求都发往 HiAPI 统一 API 主机;端点路径即模型标识符。
  3. 一张源图,可访问或可编码——要么是公开 HTTPS URL,要么是 base64 载荷,取决于请求 schema 接受哪种形式。
  4. 一个 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,然后接入上述提交与轮询模式。

立即开始构建持久 AI 产物

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

阅读 API 文档