如何使用 Kling 2.5 Turbo 图生视频 API（curl + Python）

TL;DR

• kling-2.5-turbo/image-to-video 可将一张首帧图像转换为 5 秒或 10 秒的视频片段；传入第二张图片 URL 可固定最后一帧。该模型运行在 HiAPI 的异步任务 API 上——先 POST /v1/tasks 创建任务，然后轮询 GET /v1/tasks/{taskId} 获取生成的 MP4。
• 输出费用为每秒 $0.06：5 秒片段 $0.30，10 秒片段 $0.60。计费按完成的每秒输出计算，因输入无效而失败的任务不会产生输出，也不会收费。
• 输入 schema 是严格且封闭的。必填：image_urls（数组，1–2 项——注意是复数）、prompt、duration（只能为 5 或 10）。可选：aspect_ratio、negative_prompt、cfg_scale。单数形式 image_url 会直接被拒绝。
• 该模型已在 HiAPI 上线：打开模型页面 先在浏览器中试用，然后再接入下面的 API。

你将构建什么、需要准备什么

读完本文，你将拥有一个可用的首帧 → 视频调用：提交图像和运动提示词、轮询任务、下载 MP4。首先需要准备两样东西：

1. 从 HiAPI 仪表盘 获取 API Key——每个请求都必须以 Authorization: Bearer sk-... 形式发送。如果还没创建，请参阅 认证文档。
2. 一个可公开访问的首帧图片 URL。创建调用只检查输入的结构；图片实际上是在任务运行时才获取的，因此 localhost 或私有 URL 会创建一个随后失败的任务（详见下文）。

这是图生视频，所以模型 id 是 kling-2.5-turbo/image-to-video。如果你只想根据提示词生成视频，还有单独的 文生视频端点。

最小可运行示例（curl）

创建任务。模型名放在顶层；模型读取的所有内容都放在 input 内：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-2.5-turbo/image-to-video",
    "input": {
      "prompt": "The perfume bottle rotates slowly on the marble stand, light glints across the glass, petals drift down, slow orbit",
      "image_urls": ["https://static.hiapi.ai/gallery/2026/10/4852c542c4447593.jpg"],
      "duration": 5,
      "aspect_ratio": "9:16"
    }
  }'

创建成功会返回任务 id——而不是视频：

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5CW..." }, "message": "success" }

然后轮询详情端点，直到 status 进入终态：

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5CW... \
  -H "Authorization: Bearer sk-YOUR_KEY"

任务运行期间你会看到非终态状态；完成后可在 data.output[0].url 下获取 MP4 URL：

{
  "code": 200,
  "data": {
    "status": "success",
    "model": "kling-2.5-turbo/image-to-video",
    "storage": "temp",
    "output": [{ "url": "https://temp.hiapi.ai/kling-i2v/tk-hiapi-01M5CW.mp4?expireAt=1761350400" }]
  },
  "message": "success"
}

该 output[0].url 是临时链接——请立即下载，而不是在你的应用中直接热链引用（参见 生产环境注意事项）。

最小可运行示例（Python）

无需 SDK——HiAPI 任务 API 是纯 HTTP 接口，因此标准库就足够了：

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}


def create(image_url: str, prompt: str, duration: int = 5) -> str:
    payload = {
        "model": "kling-2.5-turbo/image-to-video",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],   # 1–2 items; 2nd = last frame
            "duration": duration,        # 5 or 10 only
        },
    }
    r = requests.post(API, json=payload, headers=HEADERS, timeout=60)
    body = r.json()
    task_id = (body.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {body}")
    return task_id


def wait(task_id: str, timeout_s: int = 600, interval: int = 5) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        task = r.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task["output"][0]["url"]
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


task_id = create(
    "https://static.hiapi.ai/gallery/2026/10/4852c542c4447593.jpg",
    "slow orbit around the product, light glints across the glass, petals drift down",
    duration=5,
)
mp4_url = wait(task_id)

# Download immediately — the URL is short-lived.
with requests.get(mp4_url, stream=True, timeout=120) as resp:
    resp.raise_for_status()
    with open("clip.mp4", "wb") as f:
        for chunk in resp.iter_content(1 << 16):
            f.write(chunk)
print("saved clip.mp4")

生产环境注意事项

轮询或使用回调。 每 5 秒轮询一次（如上所示）是最简单的路径，也是示例所用的方式。如果你更希望被推送结果，创建调用接受顶层 callback 对象——{"url": "https://you/webhook", "when": "final"}——任务进入终态后 HiAPI 会向你的端点发送 POST 请求。确切的 webhook 契约见 创建任务文档；对于大多数单片段任务，轮询 任务详情端点 就足够了。

始终基于 data.status 分支，绝不要基于创建调用的 HTTP 状态码。 创建返回 200 意味着已接受，而非已渲染。只有详情端点返回 status: "success" 时，片段才真正存在。

将输出 URL 视为临时链接。 storage 为 temp，URL 会过期，因此任务成功后应立即下载 MP4（或将其复制到你自己的存储桶）。不要将 HiAPI URL 直接提供给终端用户。

成本控制。 你按完成的每秒输出付费——$0.06/秒——因此 5 秒片段为 $0.30，10 秒片段为 $0.60。在迭代提示词和首帧期间先用 5 秒渲染，满意后再以 10 秒重新运行。最新价格见 定价页面。

实测笔记与注意事项

本文所有内容均来自对线上端点的真实请求（schema 于 2026-10-21 重新验证），而不仅仅是参数表：

• 字段是 image_urls（复数），且 schema 是封闭的。 发送看似自然的 image_url 会在任务创建前失败：

  { "code": 400, "error_code": "INVALID_REQUEST",
    "message": "invalid input: image_urls: missing required field \"image_urls\"; <root>: additional properties 'image_url' not allowed" }
  

  任何无法识别的字段（mode、拼写错误等）都会以同样方式被拒绝——不存在被静默忽略的额外字段。
• duration 是枚举，不是范围。 只接受 5 和 10；7 会返回 duration: value must be one of 5, 10。
• image_urls 包含 1 或 2 项。 一个 URL 是首帧；第二个 URL 固定最后一帧，以实现受控转场。三个 URL 返回 maxItems: got 3, want 2；空数组返回 minItems: got 0, want 1。
• 确实存在的可选字段： aspect_ratio 只接受 16:9、9:16、1:1、4:3、3:4、21:9；cfg_scale 上限为 1（传入 99 返回 cfg_scale: maximum: got 99, want 1）；negative_prompt 必须是字符串。省略 aspect_ratio 可让模型跟随你的首帧。
• 创建调用只验证结构，不验证可达性——这是最容易踩坑的一点。 语法有效但无法访问的图片 URL 会返回 200 和 taskId，随后任务会异步转为失败：

  { "data": { "status": "fail",
    "error": { "code": "INVALID_REQUEST",
      "message": "The image URL is not readable. Please provide a valid public HTTP(S) URL or an accessible file path and try again." } } }
  

  该任务没有产生 output，也未计费——失败不产生费用——但如果你只检查创建响应，会误以为它成功了。这正是轮询循环要基于 data.status 判断的原因。

相关内容

• Kling 2.5 Turbo 图生视频模型页面 —— 在浏览器中试用，无需代码。
• Kling 2.5 Turbo 文生视频 —— 无需起始帧，直接根据提示词生成。
• 6 个 Kling 2.5 Turbo 提示词模板 —— 可直接复制的提示词，涵盖产品、竖屏、旅行、美食、宠物和转场。
• 创建任务 和 任务详情 文档 —— 完整的异步任务参考，包括回调。
• 快速开始 —— 如果这是你第一次调用 HiAPI，这里是五分钟版本。

常见问题

片段可以多长？ 5 秒或 10 秒——这是 schema 接受的仅有的两个 duration 值。

我可以控制结尾吗？ 可以。在 image_urls 中放入两个 URL：第一个是开场帧，第二个是最后一帧。模型会在两者之间插值生成运动。

为什么创建返回 200，但任务却显示 fail？ 创建调用只检查你的 JSON 是否符合 schema。图片是在任务运行时才获取的，因此无法访问或私有的 URL 会创建任务，然后使任务失败。始终从详情端点读取 data.status，并确保首帧 URL 可公开访问。

失败的任务会收费吗？ 不会。你按完成的每秒输出计费，因此因输入无效而失败的任务不会产生 output，也不会收费。

有宽高比控制吗？ aspect_ratio 是可选的，接受 16:9、9:16、1:1、4:3、3:4 或 21:9。留空则跟随你的首帧。