教程
如何通过 HiAPI API 使用 kling-3.0/motion-control:curl 与 Python 示例
本页内容
kling-3.0/motion-control 的用途与选用时机
运动控制是视频生成中的一类能力:你把一段参考视频交给模型,由它来驱动输出中的运动、节奏和构图,而不是仅靠文本提示词描述动作。在 HiAPI API 上使用 kling-3.0/motion-control 时,参考视频是主要输入:它锚定物体如何运动,其他参数则塑造围绕该运动生成的内容。
当运动本身是难点时,应选择该模型。适合的典型场景:
- 你有一段短视频,希望用不同的内容复现其镜头运动或主体动作。
- 你需要可预期的运动,而不是靠文本提示词碰运气的文生视频结果。
- 你正在构建一条流水线,其中运动是可跨多次生成复用的资产,因此它应作为输入而非一句话描述。
如果你只需要文生视频、没有运动参考,那么运动控制只会增加上传步骤和更严格的输入约束,却没有收益。同样,如果参考视频很长或构图不稳定,请预期更多次重试。本指南余下部分假设你已确定运动控制是合适的工具,并希望获得可靠、可复制的集成方式。
前置条件与端点设置
首次调用前,请先准备好三件事。
1. API 密钥
在 HiAPI.ai 账户控制台创建密钥,并将其存入环境变量,而不要写进源代码:
export HIAPI_API_KEY="your_api_key_here"
每个请求都将其作为 bearer token 发送:Authorization: Bearer $HIAPI_API_KEY。
2. 基础 URL 约定
所有 HiAPI 调用共享同一个基础 URL 和带版本号的路径前缀。请将基础 URL 放在配置中,以便切换环境时无需改动调用点:
export HIAPI_BASE_URL="https://api.hiapi.ai"
3. 模型标识符
模型通过请求中的 model 字段按请求选择,需使用精确标识符 kling-3.0/motion-control。不要在多处硬编码——将其作为常量传入,这样未来更换模型只需改一行。
你还需要一个可供 API 拉取参考视频的托管位置。通常做法是使用带签名的限时 URL;请确保无需自定义请求头或 cookie 即可访问。
这三项就绪后,剩下的工作就是请求结构与任务生命周期。
提供参考视频与运动参数
运动控制请求在概念上分为两半:运动来源(你的参考视频)和生成设置(模型应产出什么)。
参考视频
参考视频以 URL 形式放在请求体中,而不是在 JSON 载荷里传原始字节。两条实用规则:
- 使用在任务排队和处理期间始终有效的 URL。带签名的 URL 提前过期,是任务在提交几分钟后失败的常见原因。
- 保持视频简短且画面稳定。过长、抖动严重或频繁剪辑的参考素材会给模型提供含糊的运动信号。
如果素材存放在私有存储中,请在提交时生成有效期足够长的签名 URL,而不是在上传时生成。
运动与输出参数
通常与参考视频一同设置的参数:
- 描述目标内容的文本提示词,该内容应由参考运动来驱动。
- 输出宽高比与时长设置,使生成视频匹配你的展示位置。
- 模型暴露的任何运动强度或贴合度设置,用于在忠实于参考与提示词自由度之间权衡。
请将这些参数作为客户端中一个小而显式的配置对象,而不是分散在函数参数中。这样便于准确记录提交了什么,而这是该模型最有用的调试材料。
最后,提交前先校验:参考 URL 返回媒体内容类型,提示词非空,所有数值设置均在文档范围内。本地检查只需毫秒;被拒绝的异步任务则要付出一次往返和困惑的代价。
异步任务:提交、轮询并读取结果
运动控制不会在提交响应中返回视频,而是返回一个你需要跟踪的任务。请从一开始就围绕该生命周期构建客户端。
第 1 步 — 提交
向模型端点 POST 任务。成功提交会返回任务标识符。立即持久化该 ID——它是你操作该任务的唯一句柄,轮询和支持请求都会用到。
第 2 步 — 轮询
用该 ID GET 任务状态。状态字段会告诉你处于以下三种情况之一:
- 待处理或排队中:已接受,尚未开始。继续等待。
- 处理中或运行中:正在进行。继续等待,但采用退避策略。
- 终态:成功或失败。停止轮询。
轮询循环应显式检查终态,而不仅仅是检查输出字段是否存在。失败的任务没有结果,把“暂无结果”当作“仍在运行”会导致无限循环。
第 3 步 — 读取结果
成功时,响应会携带输出位置,通常是生成视频的 URL。请及时下载到你自己的存储——临时 URL 背后的生成资产不应被视为永久可用。
轮询规范
两条规则可让其在生产环境中保持可靠:
- 轮询之间进行退避(从一两秒开始,然后递增),而不是猛打端点。
- 限制总等待时间,并将超时作为可重试的错误暴露出来,而不是让工作线程永久阻塞。
为每次运行记录任务 ID、提交的参数和最终状态。当出现异常时,该日志能在你询问他人之前回答大部分问题。
可运行的 curl 请求
下面是 shell 中的完整流程。它提交任务,提取任务 ID,然后轮询直到任务进入终态。
#!/usr/bin/env bash
set -euo pipefail
BASE="$HIAPI_BASE_URL"
MODEL="kling-3.0/motion-control"
# 1) 提交任务
SUBMIT=$(curl -sS -X POST "$BASE/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-3.0/motion-control",
"prompt": "一只纸船漂过雨中的城市街道,电影感",
"reference_video_url": "https://your-bucket.example.com/refs/pan-left.mp4",
"duration": 5,
"aspect_ratio": "16:9"
}')
echo "$SUBMIT"
TASK_ID=$(echo "$SUBMIT" | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])')
echo "task: $TASK_ID"
# 2) 轮询直到终态
while true; do
STATUS_JSON=$(curl -sS "$BASE/v1/videos/generations/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY")
STATUS=$(echo "$STATUS_JSON" | python3 -c 'import sys,json; print(json.load(sys.stdin)["status"])')
echo "status: $STATUS"
case "$STATUS" in
succeeded) echo "$STATUS_JSON"; break ;;
failed|cancelled) echo "$STATUS_JSON" >&2; exit 1 ;;
esac
sleep 3
done
关于改编此脚本的两点说明。第一,将模型标识符和端点路径保存在变量中,使脚本保持可读。第二,上面的解析不使用 jq,只用 Python,是因为 Python 几乎随处可用;如果你偏好 jq,可以替换。无论哪种方式,关键行为相同:从提交响应中提取任务 ID,然后轮询其状态,直到看到终态值。
同样的请求(Python 版本)
下面的 Python 客户端与 curl 流程对应,但轮询循环更健壮:近似指数退避、总体超时,以及对每个终态的显式处理。
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-3.0/motion-control"
HEADERS = {
"Authorization": f"Bearer {KEY}",
"Content-Type": "application/json",
}
TERMINAL = {"succeeded", "failed", "cancelled"}
def submit_job(prompt: str, reference_video_url: str, duration: int = 5) -> str:
payload = {
"model": MODEL,
"prompt": prompt,
"reference_video_url": reference_video_url,
"duration": duration,
"aspect_ratio": "16:9",
}
r = requests.post(
f"{BASE}/v1/videos/generations",
headers=HEADERS,
json=payload,
timeout=30,
)
r.raise_for_status()
return r.json()["id"]
def wait_for_job(task_id: str, timeout_s: int = 600) -> dict:
deadline = time.time() + timeout_s
delay = 2.0
while time.time() < deadline:
r = requests.get(
f"{BASE}/v1/videos/generations/{task_id}",
headers=HEADERS,
timeout=30,
)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status in TERMINAL:
return data
time.sleep(delay)
delay = min(delay * 1.5, 15.0)
raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")
if __name__ == "__main__":
task_id = submit_job(
prompt="一只纸船漂过雨中的城市街道,电影感",
reference_video_url="https://your-bucket.example.com/refs/pan-left.mp4",
)
print("submitted:", task_id)
result = wait_for_job(task_id)
if result["status"] == "succeeded":
print("output:", result.get("output"))
else:
print("job did not succeed:", result)
改编时值得保留的部分:终态集合、有上限的退避,以及独立的提交和等待函数。在真实服务中,你会把它们拆到两个进程中——从请求处理器提交,存储任务 ID,让 worker 轮询——这样慢任务永远不会阻塞 HTTP 响应。
常见故障点及其调试方法
kling-3.0/motion-control 的大多数集成问题都落在少数几类中。请按顺序检查。
认证与模型错误
401 几乎总是意味着 bearer token 缺失、被截断,或取自错误的环境。模型未找到错误意味着 model 字符串不完全匹配——它是用斜杠分隔的标识符,因此字符顺序错误或多余空白会在配置中静默失败,而在 API 处大声报错。
参考视频不可用
任务被接受,几分钟后却因为无法拉取参考 URL 而失败。原因按频率排序:签名 URL 在处理前过期;URL 需要服务未发送的认证头;URL 返回 HTML(登录页或错误页)而不是视频。请从你的网络外部用普通 curl 测试该 URL,并确认内容类型。
参数格式错误或超出范围
时长和宽高比设置超出文档范围会在提交时被拒绝,这算是好事——你会立即得到错误。请在本地先校验,这样拼写错误就不需要往返一次才发现。
轮询缺陷
两个经典问题:循环只检查输出字段而从不检查 failed,导致无限循环;以及在无休眠的紧密循环中轮询,导致自己被限流。请添加显式终态检查和退避,并在错误报告中始终附上任务 ID,以便查询任务而不是重建任务。
结果 URL 过期
你生成了视频,但只保存了临时输出 URL。任务成功后应立即将输出下载到你自己的存储;把返回的 URL 视为拉取句柄,而不是持久存储。
每次调试会话开始时,先记录确切的请求体和原始响应 JSON。上述几乎所有问题都能在这两个材料中看到。当你准备进一步深入时,请查阅 HiAPI.ai 文档中的其他视频模型和端点参考,并保持同样的“先提交后轮询”客户端形态。