博客

教程

通过 HiAPI API 调用 veo-3.1/image-to-video:curl 与 Python 教程

2026年11月12日
封面图:骨白色纸张层层错位堆叠,一张锈红色隔纸夹在中间,投影平直。
本页内容

veo-3.1 图像转视频端点期望什么

在写第一行代码之前,先弄清楚这是一次什么样的调用会很有帮助。veo-3.1/image-to-video 不会在你发送提示词的那个 HTTP 响应里直接返回视频。它是一个异步任务端点:你描述想要的视频,平台接受任务,然后你再回来查询结果。

从概念上讲,一个请求包含两个截然不同的部分:

  • 首帧图像。 这是生成视频的起始静帧。它锚定了开场时刻的构图、主体和观感。后续一切内容都由模型从这一起点生成。
  • 生成选项。 这些是控制视频如何生成的参数——例如是否生成音频、输出分辨率,以及片段时长。

这种拆分之所以重要,有两个原因。第一,它让故障更容易推理:图像问题看起来和参数问题不同,你希望能把两者区分开。第二,这意味着你的代码也应按同样方式组织——一部分逻辑负责准备图像,另一部分负责构建选项集合。

调用方至少必须提供:有效的首帧图像,以及对音频、分辨率和时长的决定。其余一切——提交任务、跟踪状态、返回最终视频——都由平台的任务生命周期处理。你的集成只需做三件事:发送格式正确的请求、记住返回的任务标识符,并轮询直到任务进入终态。

继续之前有一个实用提示:由于调用是异步的,你的代码不能假设提交后视频立即可用。从一开始就围绕这一点设计流程,后面的教程就会显得顺理成章。

两部分的思维模型

阅读以下章节时请保持这个框架:

  1. 输入 → 经准备和校验的首帧图像。
  2. 选项 → 音频、分辨率、时长。
  3. 任务 → 提交、获取标识符、轮询、取回。

下面的每一节都对应其中一个方框。

准备首帧图像

首帧图像是图像转视频调用中最重要的单一输入,因此在流水线中给它一个专门的步骤,而不是把它埋在请求构建器里。API 调用必须能够引用该图像,这意味着图像必须处于平台可接受和读取的形式。

发送前要检查什么

  • 图像确实能打开。 下载被截断或文件损坏是下游出现令人困惑的失败的最常见原因。发送任何内容之前,先验证它能正常解码。
  • 格式是平台接受的。 如果你的来源是截图、手机照片或设计工具导出文件,请在上传前将其规范化为广泛支持的格式。提前转换一次比事后调试更省事。
  • 尺寸合理。 极小或极度拉伸的图像给模型提供的素材很少。如果来源太小,考虑放大或选择更好的帧。
  • 构图是好的起点。 因为这是首帧,生成的运动会从它继续。选择主体清晰可见、且你乐于在片段开头看到该构图的帧。

与选项保持分离

组织代码时,让图像准备返回一个可交给请求构建器的引用,而不是把图像处理与参数组装混在一起。具体来说:

# 伪代码结构,不是完整客户端
def prepare_first_frame(path):
    image = load_and_validate(path)   # 解码、检查格式、检查尺寸
    ref = upload_or_encode(image)     # 生成 API 调用可引用的内容
    return ref

def build_request(first_frame_ref, options):
    return {
        "first_frame": first_frame_ref,
        # 音频 / 分辨率 / 时长放在这里
    }

这种分离在调试时很有回报。如果任务失败,你可以单独重跑 prepare_first_frame,在触碰任何生成参数之前确认图像侧是健康的。

尽早校验,大声失败

在你这一侧完成校验,并在失败时抛出清晰的错误。格式错误或无法读取的图像绝不应到达网络——在本地捕获它,就能把模糊的异步任务失败变成你自己编写的、精确且即时的异常。

设置生成选项:音频、分辨率和时长

图像处理完毕后,剩下的决定就是生成选项。它们会改变输出的性质,因此应把它们当作显式的命名参数,而不是埋在请求体里的魔法值。

音频

音频选项控制生成的视频是否包含音轨。这既是一个技术决定,也是一个产品决定:

  • 如果视频将静音嵌入——背景循环、自动播放的主视觉——通常不需要音频,省去它能让下游处理更简单。
  • 如果片段要带声音独立呈现——短社交内容、演示——则启用音频,这样一次调用就能得到完整素材。

按用例有意决定,而不是盲目采用默认值;它既影响输出,也影响你的下游流水线如何处理该文件。

分辨率

分辨率决定最终视频的像素尺寸。根据视频将在哪里展示以及内容需要多少细节来选择,而不是简单地选“可用的最大值”。为小型嵌入式播放器渲染的片段,以远超显示面板能力的尺寸生成并无益处。如果平台公布了受支持的取值集合,请从中显式选择,并在客户端中据此校验,让不支持的取值快速失败。

时长

时长设定生成片段的长度。它与你的内容规划相互作用:一个需要先建立场景、再展示运动的镜头,比单个手势需要更多时间。注意,这是最可能被计量的参数之一——平台的计费以生成输出为口径描述,因此批量请求时要留意片段有多长。

把选项组装成一个对象

把三者放在同一个选项结构里,这样只有一个地方可查看、一个地方可修改:

options = {
    "audio": True,          # 生成音轨
    "resolution": "...",    # 受支持取值之一
    "duration": 8,          # 生成视频的秒数
}

使用你的账户和当前端点文档列为支持的值——从文档中读取,而不是硬编码猜测,并在构建请求时校验,这样坏值永远不会变成失败的任务。

用 curl 提交任务

现在把两部分合在一起并提交。从命令行开始,因为 curl 让请求形态可见,并给你一种在写入代码前快速测试改动的方式。

请求

提交请求在结构上如下所示——把占位符值替换为你自己的凭据、图像引用和选项值:

curl -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_frame": "<来自上传步骤的图像引用>",
    "audio": true,
    "resolution": "<受支持的值>",
    "duration": 8
  }'

有几个值得养成的约定:

  • 把密钥放在环境变量($HIAPI_API_KEY)中,而不是粘贴到命令里。这个习惯会直接延续到你的 Python 代码中,并让密钥远离 shell 历史记录。
  • 用显式的 Content-Type 头发送 JSON。
  • 在请求体中将图像引用与数值和布尔选项分开,呼应第一节的两部分模型。

读取响应

因为这是异步端点,成功响应不是视频。它只是任务被接受的确认,并携带跟踪所需的信息——最重要的是任务标识符,通常还有指示任务已排队或正在运行的状态字段。

分两步读取。首先,确认 HTTP 状态表示接受而非客户端错误。其次,解析响应体并提取任务标识符:

curl -s -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | tee submit.json

把响应写入 submit.json,你就有东西可检查,也可送入轮询步骤。如果提交失败,错误响应体是你第一且最好的线索——检查它指向图像引用还是某个选项,然后单独修复那一半并重新提交。

轮询异步任务直到视频就绪

拿到任务标识符后,工作流就变成一个循环:向平台询问任务状态,并在任务进入终态时停止。

生命周期

图像转视频任务会经历少量状态。它被接受并排队,然后被处理,最终要么成功并产出视频,要么失败并给出错误。你的轮询代码只需区分三件事:

  • 仍在处理——继续等待。
  • 成功——读取输出位置并下载或存储视频。
  • 失败——停止并抛出错误。

负责任地轮询

两个习惯能让轮询更稳健:

  1. 检查之间等待。 紧凑循环猛打状态端点浪费请求且毫无收益;生成需要真实时间。使用固定间隔或温和的退避。
  2. 设置截止时间。 永远不要无限轮询。选择最大尝试次数或最大耗时,并把超出它视为可清晰报告的失败。
# 轮询循环草图
for i in $(seq 1 60); do
  status=$(curl -s "https://api.hiapi.ai/v1/jobs/<job_id>" \
    -H "Authorization: Bearer $HIAPI_API_KEY")
  echo "$status"
  # 当状态字段报告成功或失败时跳出
  sleep 5
done

把确切的状态字符串和端点路径当作需要对照当前 API 文档确认的事项,而不是固化在脚本里的假设。

成功时

当任务报告成功时,响应携带最终视频的位置。及时下载并存储到持久位置——任何异步平台上的任务结果都应被视为现在就要取回的东西,而不是很久以后才懒加载获取的东西。把任务标识符与存储文件一同记录,这样任何输出都能追溯到产生它的请求。

Python 中的同一请求

Python 版本不应是第二套实现——而应是同一个请求,表达一次并复用。目标是单个提交并轮询的函数,由你此前校验过的同一图像引用和同一选项对象构建。

一个请求体,一个客户端

import os
import time
import requests

BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
})

def build_body(first_frame_ref, options):
    return {"first_frame": first_frame_ref, **options}

def submit(body):
    r = session.post(f"{BASE}/veo-3.1/image-to-video", json=body, timeout=60)
    r.raise_for_status()
    data = r.json()
    return data["job_id"]

def poll(job_id, interval=5, max_attempts=60):
    for _ in range(max_attempts):
        r = session.get(f"{BASE}/jobs/{job_id}", timeout=30)
        r.raise_for_status()
        data = r.json()
        state = data.get("status")
        if state in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError(f"任务 {job_id} 未能及时完成")

def image_to_video(first_frame_ref, options):
    job_id = submit(build_body(first_frame_ref, options))
    result = poll(job_id)
    if result["status"] == "failed":
        raise RuntimeError(result.get("error", "任务失败"))
    return result  # 包含最终视频位置

为什么是这个形态

  • 一个 Session。 复用会话把认证头放在一处,并在提交和每次轮询之间复用连接。
  • 一个 build_body。 curl 请求和 Python 请求是同一个请求体——相同的键、相同的值。当你修改某个选项时,只在一处修改。
  • 显式超时和截止时间。 两个调用都设置超时,且 poll 有尝试次数限制,因此停滞的任务永远不会挂住你的进程。
  • 失败会大声暴露。 提交时的 raise_for_status 立即捕获请求级错误;image_to_video 中显式的失败分支捕获任务级失败。

如果以后需要通过同一平台调用其他模型,这个结构可以泛化:会话、提交辅助函数和轮询辅助函数保持不变,只有端点和请求体构建器改变。

排查失败的图像转视频调用

当调用没有产出视频时,通过询问哪个阶段失败来缩小范围。两部分请求模型给你一份清晰的检查清单。

阶段 1:提交被拒绝

如果提交调用本身返回错误,则什么也没生成——这是好消息,因为问题出在请求中。

  • 图像引用问题。 最常见的单一原因。单独重跑图像准备步骤,确认它产出有效、可读、格式正确的图像以及 API 接受的引用。首先检查上传截断和不支持的格式。
  • 无效选项值。 不支持的分辨率或超出范围的时长会在提交时被拒绝。发送前对照文档中的受支持值校验选项。
  • 认证和请求头。 确认密钥确实被发送(Authorization: Bearer ...),且请求体以 JSON 发送。在 curl 中手工构建请求时,空或畸形的请求体很容易被忽略。

阶段 2:任务已提交但失败

如果提交被接受但轮询以失败告终,说明请求格式正确,问题在内容或任务本身。

  • 阅读任务错误。 失败响应比猜测能更好地解释哪里出了问题。原样记录它。
  • 查看首帧。 没有清晰主体、极端裁剪或严重扭曲的源图像给模型提供的素材很少。换入更干净的帧并重试。
  • 重新考虑选项。 很长的时长或不寻常的设置组合值得用更简单的配置重测,以隔离出哪个参数有问题。

阶段 3:轮询永不结束

如果你的循环超时而非失败,把它当作基础设施问题,而不是内容问题。确认你在轮询正确的任务标识符、间隔不太激进,且截止时间对于请求的时长足够长。提交时记录任务标识符——没有它,你根本无法调查卡住的任务。

有效的调试流程

出问题时,按这个顺序进行:本地校验图像,再次提交并捕获原始响应,若出现任务错误则检查它,然后简化选项并重试。每一步都正好测试请求的一半,这就是为什么在代码中把图像和生成参数分开,恰好在出错时带来回报。

至此,你已拥有完整循环:准备首帧,设置音频、分辨率和时长,异步提交,并轮询至完成——无论用 curl 还是 Python 运行,都是同一个请求。

立即开始构建持久 AI 产物

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

阅读 API 文档