Python 中的 Kling AI 图生视频 API

通过 HiAPI 的异步任务端点，在 Python 中使用 Kling AI 图生视频 API。下面的快速开始使用当前可调用的 kling-3.0-omni/image-to-video 模型 ID，轮询任务直到进入终态，并下载生成的 MP4。

要查准确字段，请打开 Kling 3.0 Omni 图生视频 API 文档。使用当前 Omni 模型页面查看模型和 Playground，并在生产运行前核对实时 Kling API 价格。

快速开始：在 Python 中运行 Kling 图生视频

用 python -m pip install requests 安装 requests，在环境中设置 HIAPI_API_KEY，并将 IMAGE_URL 替换为公开的 JPEG、PNG 或 WebP URL。完整脚本就是第一个可复制的代码块：

import os
import time
from pathlib import Path

import requests

API_BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
IMAGE_URL = "https://cdn.example.com/first-frame.jpg"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "kling-3.0-omni/image-to-video",
    "input": {
        "image_urls": [IMAGE_URL],
        "prompt": "The camera slowly pushes in as leaves move in a light breeze",
        "duration": 5,
        "resolution": "1080p",
        "sound": False,
    },
}

created = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json=payload,
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["taskId"]

deadline = time.time() + 900
while time.time() < deadline:
    response = requests.get(
        f"{API_BASE}/tasks/{task_id}",
        headers=HEADERS,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()["data"]

    if task["status"] == "success":
        output_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(task.get("error") or f"Task {task_id} failed")

    time.sleep(8)
else:
    raise TimeoutError(f"Task {task_id} did not finish within 15 minutes")

with requests.get(output_url, stream=True, timeout=180) as download:
    download.raise_for_status()
    with Path("kling-output.mp4").open("wb") as video:
        for chunk in download.iter_content(1024 * 1024):
            if chunk:
                video.write(chunk)

print("Saved kling-output.mp4")

创建请求会返回一个 taskId，并不会等待视频生成完成。脚本会轮询 GET /v1/tasks/{taskId}，在 success 或 fail 时停止，并尽快下载第一个输出，因为结果 URL 会过期。

打开 Kling Omni 模型并试用此 payload。

选择当前可用的 Kling 图生视频模型

模型 ID	适用场景	输入与输出约定
kling-3.0-omni/image-to-video	需要首帧/尾帧控制、可选的原生声音或 4K	一到两个公开图片 URL；3-15 秒；720p、1080p 或 4K
kling-3.0-turbo/image-to-video	只需一个起始帧，且 720p/1080p 的更简单 schema 即可满足需求	恰好一个公开图片 URL；prompt 必填；3-15 秒；720p 或 1080p

Omni 的完整字段参考见 Omni I2V 文档。Turbo 有单独的 Turbo I2V schema 参考。两者都使用相同的 /v1/tasks 创建与轮询工作流，因此可以保留一个执行器，只替换 model 和 input。

符合模型要求的请求体

带首帧和尾帧的 Omni

发送一个 URL 表示首帧，或发送两个 URL 并按照 [first, last] 的顺序排列：

{
  "model": "kling-3.0-omni/image-to-video",
  "input": {
    "image_urls": [
      "https://cdn.example.com/first-frame.jpg",
      "https://cdn.example.com/last-frame.jpg"
    ],
    "prompt": "The camera arcs around the subject as the light changes from dawn to noon",
    "duration": 8,
    "resolution": "1080p",
    "sound": true
  }
}

Omni 接受一个或两个 image_urls。其 prompt 可选，duration 为 3 到 15 的整数，resolution 为 720p、1080p 或 4K，sound 可选。

带一个起始帧的 Turbo

{
  "model": "kling-3.0-turbo/image-to-video",
  "input": {
    "prompt": "The subject turns toward the camera while leaves move in a light breeze",
    "image_urls": ["https://cdn.example.com/first-frame.jpg"],
    "duration": 8,
    "resolution": "1080p"
  }
}

Turbo 要求提供 prompt，并且 image_urls 中恰好有一个条目。不要发送仅 Omni 支持的字段（例如 sound），也不要添加文生视频字段（例如 aspect_ratio）；画面由源图片决定。

Kling AI 价格：使用实时档位，不要照抄价格

HiAPI 上的 Kling AI 价格按使用量计费。当前两个图生视频模型都按生成的秒数计费，具体费率由模型和分辨率决定；Omni 还有不同的开启音频档位。更长的片段、更高的分辨率或原生音频都会改变任务费用。

费率可能变化，因此本指南不固定美元价格表。在预算或提交大批量任务前，请立即查看实时模型价格表。

Kling AI 免费吗？

不是：在 HiAPI 上，Kling 图生视频 API 生成并非无限免费的 API。成功的任务会按所选模型、时长、分辨率和音频设置的实时费率消耗余额。账户促销或新用户奖励可能变化，也可能附带条件，因此不要将其视为有保证的 Kling 免费档位；提交任务前，请在账户中核实现行优惠和您的余额。

可防止任务失败或重复的生产检查

1. 使用可直接下载的 HTTPS 图片 URL。localhost、需要登录的页面、HTML 分享页面和已过期的签名 URL 可能在任务创建后失败。
2. 在重试 worker 之前保存 taskId。重试创建调用可能会创建并计费第二个任务。
3. 将 success 和 fail 视为终态。在生产环境中，使用顶层 callback.url，并保留轮询作为对账兜底。
4. 及时下载 output[].url，并将长期保留的结果复制到您可控的存储中。
5. 发送前验证所选模型的 schema。严格模型约定会拒绝未知字段。

常见错误

• HTTP 400：请求与 schema 不匹配，请检查指出的字段、枚举值、数组长度和 JSON 类型。
• HTTP 401：bearer key 缺失、无效，或无法使用所选模型。
• 任务进入 fail：创建请求通过了校验，但渲染器无法获取输入或完成生成。请将 taskId 和返回的错误与创建响应分开记录。
• 输出 URL 已过期：渲染可能已成功，但临时取件 URL 未及时下载。

常见问题

在 Python 中应该使用哪个 Kling 图生视频模型？

需要一到两帧控制、可选的原生声音或 4K 时，使用 kling-3.0-omni/image-to-video。当一个起始帧和 720p/1080p 输出即可满足需求时，使用 kling-3.0-turbo/image-to-video。Python 的创建、轮询和下载代码保持不变。

当前 Kling AI 图生视频模型 ID 是什么？

本文涵盖的当前可调用 ID 是 kling-3.0-omni/image-to-video 和 kling-3.0-turbo/image-to-video。在 POST /v1/tasks 的顶层 model 字段中发送任一 ID 即可。

Kling 图生视频可以接受多少张图片？

Omni 接受一张作为首帧的图片，或按 [first, last] 顺序接受两张图片。Turbo 恰好接受一张起始帧图片。

Kling AI API 费用是多少？

按生成的秒数计费。确切的实时费率取决于模型和分辨率，Omni 还取决于音频设置。请使用实时价格页面，不要照抄本指南中的静态价格。

通过 API 使用 Kling AI 免费吗？

不承诺提供无限的 Kling API 免费档位。生成会按实时任务费率消耗账户余额。请查看账户中是否有当前附条件的 starter 优惠，而不要假定有固定的免费额度。

为什么创建请求成功后任务仍然失败？

JSON 通过了初始校验，但渲染器可能无法获取图片或完成生成。请确认图片是公开的且未过期，然后根据保存的 taskId 检查终态错误。

如何获取生成的视频？

从创建响应中读取 data.taskId。本地脚本可轮询 GET /v1/tasks/{taskId}，生产环境可使用 callback.url。在 success 时，在 data.output[0].url 过期前下载它。

接下来阅读完整的 Kling Omni API 参考，然后在准备测试请求时打开当前模型页面。