博客

教程

如何通过 HiAPI API 使用 kling-3.0/motion-control:curl 与 Python 示例

2026年11月12日
封面图:暖炭色底面上一条宽阔琥珀色光带斜向扫过,边缘干净,下方点缀少量暗色几何形。
本页内容

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 背后的生成资产不应被视为永久可用。

轮询规范

两条规则可让其在生产环境中保持可靠:

  1. 轮询之间进行退避(从一两秒开始,然后递增),而不是猛打端点。
  2. 限制总等待时间,并将超时作为可重试的错误暴露出来,而不是让工作线程永久阻塞。

为每次运行记录任务 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 文档中的其他视频模型和端点参考,并保持同样的“先提交后轮询”客户端形态。

立即开始构建持久 AI 产物

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

阅读 API 文档