教程
如何通过 HiAPI API 调用 hailuo-2.3/image-to-video:curl 与 Python
本页内容
hailuo-2.3/image-to-video 能做什么、什么时候用
hailuo-2.3/image-to-video 是通过 HiAPI 统一 API 提供的图生视频模型。你给它一张静态图片作为首帧,再加一段描述画面应如何运动的提示词,模型就会生成一段从该图片开始、并在此基础上向前推进动画的短视频。
关键词是首帧。在文生视频中,模型会根据提示词凭空构想整个画面;而图生视频会把构图、主体、光照和风格锚定在你提供的图片上。因此,当你已有需要保留的特定视觉素材——产品图、角色参考图、分镜画面、概念渲染图——并且希望在其上叠加动态效果,而不是重新演绎时,它会是更合适的选择。
适合使用此端点的场景:
- 你需要与已有素材保持连贯。产品照片不应被重新生成为略有不同的产品,而应动起来。
- 你正在基于静态帧构建分镜或动态分镜,并希望快速预览运动效果。
- 你需要可控构图:镜头和主体位置来自图片,提示词只需描述动态。
如果没有参考图,并希望由模型设计镜头,或者视觉细节更适合用文字表达而非由帧来固定,则更适合改用文生视频。
前置条件与获取 API 密钥
在首次请求之前,你需要三样东西:一个 HiAPI 账户、一个 API 密钥,以及一个可公开访问的首帧图片 URL。
账户与 API 密钥
登录 HiAPI 并在控制台创建 API 密钥。请将密钥视为机密:把它保存在环境变量中,而不是粘贴到源文件里。本指南中的示例均从 HIAPI_API_KEY 读取。
export HIAPI_API_KEY="your-api-key-here"
可访问的图片 URL
作为首帧传入的图片必须能被服务端获取——签名过的云存储 URL、CDN 链接或任意公开 HTTPS URL 均可,本地文件路径不行。如果素材位于需要认证的位置,请为请求生成有时效的签名 URL。
在自动化任何流程之前,请先在最新的 HiAPI API 参考文档中确认当前的端点路径、参数名和允许值。模型接口会演进,硬编码旧教程中看到的参数名是常见且可避免的错误来源。当前价格和任何配额规则都列在网站的价格面板上——请到那里确认,不要自行假设。
请求结构:图片输入与参数
从概念上讲,图生视频请求包含三部分:模型标识符、图片和生成参数。
模型标识符
每次调用都指向 hailuo-2.3/image-to-video。请把它集中放在代码中的一个位置,这样以后切换模型只需改一行。
首帧图片
这是视频起始静态图的 URL。它的宽高比和分辨率决定了输出的基础几何形态,因此请选择已经具有你所需构图的图片,而不是事后裁剪。一张干净、光照良好、主体清晰的图片,比一张杂乱的拼贴图能产生可预测得多的运动效果。
提示词
用于描述运动的文本字段——将在下一节介绍。
时长与分辨率
图生视频任务通常会提供剪辑长度和输出分辨率的选项。这些参数最可能随模型版本变化,因此不要凭记忆硬编码。请打开最新的 API 参考文档,阅读接受的字段名和允许值,并将这些值放入配置对象,而不是把字面量散落在代码各处。如果某个值被拒绝,API 响应通常会告诉你哪个字段有问题。
请求体为 JSON;响应返回任务标识符,而不是完成的视频,这将在下面的轮询部分讨论。
编写能产生可信运动的提示词
图片已经描述了场景里有什么。提示词的任务是描述它如何运动。重新描述主体的提示词会浪费模型能力;而明确运动、镜头行为和物理规律的提示词能产生好得多的视频片段。
描述运动,而非内容
较差示例:“一位穿红色大衣的女子站在桥上。”
较好示例:“女子缓慢转头看向镜头,大衣在风中摆动;镜头轻柔地推进。”
将主体运动与镜头运动分开
对两者都要明确。“缓慢向前推镜”、“手持漂移”、“固定镜头”和“向右环绕”告诉模型画面本身如何变化;而“头发飘动”、“蒸汽升起”和“书页翻动”则描述画面内部发生的事。将两者结合,才能得到连贯的镜头,而不是漂移不定的画面。
遵循物理规律
要求以合理速度作合理运动:“布料轻轻起伏”、“水流向下游”、“烟雾向上卷曲”。避免与场景矛盾的指令——让坐着的主体走路,或对固定机位的产品镜头要求快速摇摄,通常都会导致伪影。
保持简短具体
两三句具体、物理化的语言胜过一整段形容词。先说明主要运动,再说明镜头,最后说明光照变化等次要细节。
提交任务并轮询结果
视频生成需要时间,因此 API 是异步的。生命周期分为三步:
1. 创建任务
将图片 URL、提示词和参数 POST 到端点。成功的响应会返回任务标识符和初始状态,通常类似 queued 或 processing。该响应中还没有视频。
2. 轮询任务
针对该任务标识符定期发送 GET 请求。每次响应都会报告状态,完成后还会包含结果载荷。以合理间隔轮询——通常相隔几秒——而不是在紧密循环中轮询,并限制尝试次数,以免卡住的任务使进程永久挂起。
3. 获取视频
当状态报告成功时,响应中包含视频位置(通常是 URL),往往还有时长等元数据。请按你自己的留存规则下载或存储它。
生产环境设计要点
- 持久化任务 ID。 如果你的工作进程在轮询中途崩溃,你希望能恢复而不是重新提交并为重复任务付费。
- 处理终态失败。 任务可能失败;应把失败当作独立分支处理,而不是“继续轮询”。
- 解耦提交与轮询。 在 Web 后端中,从请求处理器提交,并从后台工作进程轮询,这样 HTTP 超时永远不会终止正在运行的生成任务。
可运行的 curl 示例
以下示例提交一个任务。请将图片 URL 和提示词替换为你自己的内容;密钥来自前面设置的环境变量。
curl -sS -X POST \
"https://api.hiapi.ai/v1/hailuo-2.3/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://your-cdn.example.com/first-frame.jpg",
"prompt": "画面主体微微转向镜头并微笑;镜头缓慢推进,柔和光线在面部流转。"
}'
响应中包含任务标识符。用 GET 请求轮询它:
curl -sS \
"https://api.hiapi.ai/v1/hailuo-2.3/image-to-video/TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
重复直到状态为终态成功,然后从载荷中读取视频 URL。此处展示的确切端点路径和字段名仅用于说明模式——在将任何内容粘贴进生产代码之前,请对照最新的 API 参考文档确认,因为模型接口确实会发生变化。
可运行的 Python 示例
此脚本提交任务,然后轮询直到完成,并包含超时和基本错误处理。
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def create_task(image_url: str, prompt: str) -> str:
resp = requests.post(
BASE,
headers={**HEADERS, "Content-Type": "application/json"},
json={"image_url": image_url, "prompt": prompt},
timeout=60,
)
resp.raise_for_status()
data = resp.json()
task_id = data.get("task_id") or data.get("id")
if not task_id:
raise RuntimeError(f"No task id in response: {data}")
return task_id
def poll_task(task_id: str, timeout_s: int = 600, interval_s: int = 5) -> dict:
deadline = time.time() + timeout_s
while time.time() < deadline:
resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
data = resp.json()
status = str(data.get("status", "")).lower()
if status in {"succeeded", "success", "completed"}:
return data
if status in {"failed", "error", "cancelled"}:
raise RuntimeError(f"Task {task_id} failed: {data}")
time.sleep(interval_s)
raise TimeoutError(f"Task {task_id} did not finish in {timeout_s}s")
if __name__ == "__main__":
task = create_task(
image_url="https://your-cdn.example.com/first-frame.jpg",
prompt="蒸汽从杯中升起;镜头缓慢向右漂移。",
)
result = poll_task(task)
print(result)
由于不同 API 版本的状态字符串可能不同,代码检查了一小组常见成功和失败值,而不是单个字面量——请在 API 参考文档中核实确切词汇,并相应裁剪集合。如果你构建多条媒体流水线,将这个辅助函数独立出来便于复用。
常见失败模式与调试方法
此端点的大多数问题可归入以下几类。
图片被拒绝或无法获取
服务必须能够下载你的图片。如果遇到获取或验证错误,请检查 URL 是否为公开 HTTPS、是否已过期(签名 URL 会过期),以及格式和大小是否在文档限制内。一个快速检查方法是在浏览器隐私窗口中打开该 URL——如果它提示登录,服务端同样无法读取。
参数无效
被拒绝的时长、分辨率或未知字段通常会返回指明该字段的验证错误。请将你的载荷与最新 API 参考文档对比,而不是与教程对比,并记录完整错误体——错误消息比仅凭 HTTP 状态码更具体。
认证错误
401 或 403 几乎总是意味着密钥缺失、格式错误或缺少访问权限。确认 Authorization 头存在,并确认环境变量确实已在运行请求的 shell 或进程中导出。
轮询超时
如果任务在你的超时后仍为 processing,先检查是否轮询了正确的任务 ID,然后延长超时时间。在生产环境中,要区分“仍在运行”和“卡住”:持久化状态并让工作进程恢复轮询,而不是重新提交,因为重新提交会浪费任务。
任务提交后失败
失败的任务通常指向提示词或图片组合——矛盾的运动指令,或与所请求运动冲突的首帧。简化提示词,尝试更干净的首帧,然后重新运行。
输出看起来不对
如果运动微弱或奇怪,修复方法几乎总是提示词:明确说明主要运动,将镜头行为与主体行为分开,并保持物理运动合理。在日志中记录请求 ID 和任务 ID,以便将不佳的视频片段与产生它的确切输入关联起来。在发布前,请到 API 参考文档和价格面板确认参数名与当前价格。