博客

教程

如何通过 HiAPI API 调用 hailuo-2.3/image-to-video:curl 与 Python

2026年11月12日
封面图:深咖啡色背景上交错的宽织物条纹,扁平编织示意图风格,点缀黄铜色小方块。
本页内容

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 参考文档和价格面板确认参数名与当前价格。

立即开始构建持久 AI 产物

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

阅读 API 文档