教程
如何通过 HiAPI API 调用 kling-4.0-flash Reference-to-Video:curl 与 Python 实践
多参考图生视频的可运行调用实践、异步轮询与排查指南
- 模型
- kling-4.0-flash
本页内容
何时应使用参考图生视频而非文生视频
文生视频是编剧的工具:你描述一个场景,模型凭空创造一切。参考图生视频则是导演的工具:你给模型一张或多张图片,要求它生成能让这些主体、风格或构图保持可辨识的运动画面。在 HiAPI 上,这一区别体现在端点层面——kling-4.0-flash/reference-to-video 是与普通文生视频调用不同的独立路由,提前选对端点,可以避免陷入永远无法完全还原特定外观的提示词工程。
当以下任一情况成立时,请选用参考图生视频:
- 身份或产品一致性至关重要。 你有人物设定图、产品照片或吉祥物,且输出不能走样成泛化的相似形象。
- 你需要组合多个来源。 一个场景可能需要一张图确定角色、另一张图确定环境或服装。多张参考图让你可以明确表达这种构图,而不是靠散文描述。
- 风格迁移就是目的。 你希望将所给画面的色调、光照或渲染风格带入运动画面。
- 你在迭代某个镜头。 参考图让多次重跑具备可比性,因为视觉锚点固定不变,你只需调整与运动相关的参数。
当你在探索概念、没有权利清晰的图像可作为锚点,或需求本身比较抽象(“黎明时分穿过雾气的缓慢航拍”)且任何合理解读都可接受时,请继续使用文生视频。参考图会约束模型,而约束只有在你确实需要时才是有益的。
一条实用规则:如果你发现自己正在写一整段话来描述某个特定物体的确切外观,那就是切换到该端点并直接提供图片的信号。描述耗费 token 且仍会走样;参考图才能锚定。
请求结构:参考图与核心参数
该端点接受 JSON 请求体。你实际会接触的部分分为三类:参考图、提示词,以及输出塑造参数。
参考图
参考图以数组形式传入,因此同一字段可以自然地从一个图像扩展到多个图像。每个条目都是一个服务必须能够抓取的 URL。设计时需要考虑的实际约束:
- 使用可公开访问的 HTTPS URL,或你的账户有权访问的 URL。本地文件路径和
file://URI 无法被远程服务抓取。 - 优先选择稳定托管,而不是几分钟后就过期的签名链接——长时间运行的任务可能在超出你预期的时刻才去抓取。
- 让每张图保持聚焦。干净的主体图比繁杂的拼贴图更有帮助,因为模型需要辨别它看到的内容。
- 顺序可能影响参考图的解读方式,因此在代码中应让数组顺序保持确定,而不是依赖字典迭代顺序。
提示词
提供参考图后,提示词应描述运动、镜头和氛围,而不是外观。说明主体如何运动、摄像机如何运动、节奏感受如何。重新描述参考图会浪费提示词预算,并可能与你刚刚提供的锚点相冲突。
输出塑造参数
除了 prompt 和参考图数组之外,请求体通常还带有控制输出格式和生成行为的字段。请把这些视为最后才调整的旋钮:先用默认值让调用成功,确认参考图确实被遵循,然后再调整输出设置。字段名和允许值在端点参考文档中有定义,发送未识别的字段是请求体被拒绝的常见原因,因此请按文档中的 schema 校验,而不是凭猜测。
心智模型很简单:参考图说明是什么,提示词说明如何运动,参数说明你拿回什么。
可用的 curl 请求
在编写客户端代码之前,检查请求体最可靠的方式是一次 curl 调用。将凭证和输入设置为 shell 变量,让 JSON 保持易读,然后发送请求。
API_KEY="$HIAPI_API_KEY"
BASE_URL="https://api.hiapi.ai" # 使用你的控制台显示的基础 URL
curl -sS -X POST "$BASE_URL/v1/kling-4.0-flash/reference-to-video" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "角色转向窗户,镜头缓慢推近;柔和的晨光,节奏平静。",
"reference_images": [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/location-window.jpg"
]
}'
运行前请检查三件事:
- 路径与版本前缀。 对照你账户中的端点文档确认确切路由;路径带版本号,过期前缀会返回未找到,而不是校验错误。
- 认证头。 密钥以 bearer token 形式放在
Authorization头中。切勿将其放在请求体或查询字符串中,否则会泄露到日志里。 - 占位符。 每个必须替换的值都明显是占位符——基础 URL 注释、两个 CDN URL、提示词。在宣布可用于生产之前,先在请求中搜索
example.com。
成功提交会返回任务标识符,而不是完成的视频。请从响应体中捕获该标识符;下一步轮询时会用到它。将响应通过 JSON 格式化工具(| jq .)处理,可以让任务 ID 一目了然,值得养成习惯。
同一调用的 Python 版本
Python 版本的主要差异在于请求体的构造方式:构建一个 dict,序列化一次,并将请求函数与轮询逻辑分开,以便各自独立测试。
import os
import requests
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
API_KEY = os.environ["HIAPI_API_KEY"]
REFERENCE_IMAGES = [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/location-window.jpg",
]
def submit_reference_video(prompt: str) -> str:
payload = {
"prompt": prompt,
"reference_images": REFERENCE_IMAGES,
}
response = requests.post(
f"{BASE_URL}/v1/kling-4.0-flash/reference-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()["task_id"]
if __name__ == "__main__":
task_id = submit_reference_video(
"角色转向窗户,镜头缓慢推近。"
)
print("submitted:", task_id)
以下注意事项可避免不必要的痛苦:
- 从环境变量读取密钥。硬编码的密钥最终会进入 git 历史和截图中。
- 使用
json=而不是data=,这样客户端会正确设置内容类型并对请求体进行转义。 - 设置显式的
timeout。默认无限等待会把停滞的连接变成挂起的工作进程。 - 在解析前调用
raise_for_status(),这样 4xx 响应体会被报告为 HTTP 错误,而不是在响应 JSON 上引发令人困惑的KeyError。 - 对照文档确认任务标识符的响应字段名,而不是假定为
task_id;相应调整提取行。
让 submit_reference_video 只返回 ID。轮询是独立的关注点,应放在自己的函数中。
处理异步任务生命周期
视频生成需要时间,因此该端点在设计上就是异步的。提交调用会快速返回任务标识符;实际工作在此后发生。你的集成必须对此建模,最简单的正确模型有三种状态:pending 或 processing(继续等待)、succeeded(获取输出)、failed(读取错误并停止)。
按间隔轮询任务端点,并设置总等待时间上限:
import time
def wait_for_task(task_id: str, interval: float = 5.0, max_wait: float = 600.0) -> dict:
deadline = time.monotonic() + max_wait
url = f"{BASE_URL}/v1/tasks/{task_id}"
while time.monotonic() < deadline:
r = requests.get(url, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")
请根据文档规定调整状态字符串和任务路径——上述结构只是模式,该领域的大多数失败都源于假定了一个不存在的状态标签。
值得尽早采用的轮询礼仪:
- 逐渐退避。 固定的短间隔会毫无益处地反复冲击 API。从适中的值开始,并增加每次尝试之间的休眠时间。
- 始终限定循环。 围绕远程任务的
while True就是在等待故障发生。上述截止时间会抛出异常而不是挂起。 - 持久化任务 ID。 如果你的进程在提交后崩溃,该 ID 是无需为第二次生成付费就能恢复结果的唯一途径。
- 将
failed视为终态。 不要通过再次轮询来重试失败任务;读取错误,并在合适时重新提交修正后的请求体。 - 显式处理过期。 任务结果可能无法永久获取,因此任务一旦成功,就立即下载并存储输出。
常见错误及修复方法
大多数首次集成失败都归入少数几类。在更改代码之前,先将症状与原因对应起来。
认证与授权失败
401 或 403 几乎总是意味着凭证错误、缺失或作用域不正确。检查请求头是否恰好为 Authorization: Bearer <key>,检查该环境变量在发起调用的进程中是否确实已填充(shell 导出不会传递到 systemd 单元),并检查密钥是否已被轮换或撤销。
参考图问题
如果请求因图片被拒绝,或生成时忽略了某张参考图,嫌疑就在 URL 上。验证链接能否从你的机器外部解析——内部主机名或 localhost 地址对服务来说不可达。检查签名 URL 的过期时间,检查文件确实是图片,而不是以 200 状态返回的 HTML 错误页面,并检查尺寸和格式限制。多图数组中的一个坏条目可能导致整个请求失败,因此调试时请逐张测试参考图。
无效请求体
带有校验消息的 400 通常意味着请求体格式错误:顶层是数组而不是对象、缺少必填字段、reference_images 以带引号的字符串而非数组发送,或参数名未被识别。将你的请求体与文档 schema 逐字段比较,并记录你发送的确切请求体——缺陷常常是测试路径与生产路径之间的序列化差异。
路由或方法错误
404 通常意味着路径错误,而不是模型不可用。对照文档重新检查版本前缀和端点名称,并确认提交使用 POST、任务状态查询使用 GET。
超时与轮询错误
如果提交本身超时,适度提高客户端超时并重试——但如果任务已被接受,不要盲目重新提交,否则你将支付重复生成费用。如果轮询永不终止,你的状态检查很可能比较了错误的字符串;在前几次轮询时记录原始状态值,看看实际返回什么。
速率限制
429 意味着需要放慢速度。遵守给定的间隔,而不是立即重试,并应用带抖动的指数退避,以免并行工作进程同步重试。
上线前的生产检查清单
笔记本里能运行的代码并不等于可靠的集成。在将此端点暴露给用户之前,请收紧运维边界。
- 配置。 将基础 URL 和 API 密钥保存在环境变量或密钥管理中,绝不写入源代码。将端点路径设为常量,这样版本升级只需改一行。
- 带退避的重试。 对瞬态故障——连接重置、429、5xx——使用指数退避和抖动进行重试。不要重试 4xx 校验错误;它们会以同样方式失败。
- 幂等纪律。 记录你提交的每个任务 ID 及其输入。重启时,恢复轮询已有任务,而不是提交新任务。
- 有界等待。 为 HTTP 客户端和轮询循环都设置显式超时,并将超时路由到人工可检查的死信路径,而不是静默丢弃。
- 结构化日志。 记录任务 ID、带时间戳的状态转换、提交与完成的时序,以及失败时的错误体。对密钥进行脱敏,并在提示词包含用户数据时进行截断。
- 输出处理。 任务成功后立即将生成的媒体下载到你自己的存储,并在展示给用户前验证结果。
- 成本可见性。 计费随用量变化,因此要跟踪每个功能、每个用户提交了多少任务。在不确定性下重新提交的重试循环是意外支出的最常见原因。
- 输入卫生。 先在你这边验证参考 URL 和提示词长度。本地捕获坏 URL 比一次往返更快、更便宜。
完成这些之后,集成就是一个轻量、可预测的层:构建请求体、提交、轮询、存储。从端点参考文档开始,运行一次 curl 示例,然后将同一请求体移入 Python——在 shell 中能工作的请求,也能在你的服务中工作。