教程
通过 HiAPI API 调用 veo-3.1/image-to-video:curl 与 Python 教程
本页内容
veo-3.1 图像转视频端点期望什么
在写第一行代码之前,先弄清楚这是一次什么样的调用会很有帮助。veo-3.1/image-to-video 不会在你发送提示词的那个 HTTP 响应里直接返回视频。它是一个异步任务端点:你描述想要的视频,平台接受任务,然后你再回来查询结果。
从概念上讲,一个请求包含两个截然不同的部分:
- 首帧图像。 这是生成视频的起始静帧。它锚定了开场时刻的构图、主体和观感。后续一切内容都由模型从这一起点生成。
- 生成选项。 这些是控制视频如何生成的参数——例如是否生成音频、输出分辨率,以及片段时长。
这种拆分之所以重要,有两个原因。第一,它让故障更容易推理:图像问题看起来和参数问题不同,你希望能把两者区分开。第二,这意味着你的代码也应按同样方式组织——一部分逻辑负责准备图像,另一部分负责构建选项集合。
调用方至少必须提供:有效的首帧图像,以及对音频、分辨率和时长的决定。其余一切——提交任务、跟踪状态、返回最终视频——都由平台的任务生命周期处理。你的集成只需做三件事:发送格式正确的请求、记住返回的任务标识符,并轮询直到任务进入终态。
继续之前有一个实用提示:由于调用是异步的,你的代码不能假设提交后视频立即可用。从一开始就围绕这一点设计流程,后面的教程就会显得顺理成章。
两部分的思维模型
阅读以下章节时请保持这个框架:
- 输入 → 经准备和校验的首帧图像。
- 选项 → 音频、分辨率、时长。
- 任务 → 提交、获取标识符、轮询、取回。
下面的每一节都对应其中一个方框。
准备首帧图像
首帧图像是图像转视频调用中最重要的单一输入,因此在流水线中给它一个专门的步骤,而不是把它埋在请求构建器里。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,你就有东西可检查,也可送入轮询步骤。如果提交失败,错误响应体是你第一且最好的线索——检查它指向图像引用还是某个选项,然后单独修复那一半并重新提交。
轮询异步任务直到视频就绪
拿到任务标识符后,工作流就变成一个循环:向平台询问任务状态,并在任务进入终态时停止。
生命周期
图像转视频任务会经历少量状态。它被接受并排队,然后被处理,最终要么成功并产出视频,要么失败并给出错误。你的轮询代码只需区分三件事:
- 仍在处理——继续等待。
- 成功——读取输出位置并下载或存储视频。
- 失败——停止并抛出错误。
负责任地轮询
两个习惯能让轮询更稳健:
- 检查之间等待。 紧凑循环猛打状态端点浪费请求且毫无收益;生成需要真实时间。使用固定间隔或温和的退避。
- 设置截止时间。 永远不要无限轮询。选择最大尝试次数或最大耗时,并把超出它视为可清晰报告的失败。
# 轮询循环草图
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 运行,都是同一个请求。