Kling 4.0 图生视频 API：参考请求与一次真实运行

Kling 4.0 图生视频可将一张首帧图片制作成一段时长为 3–30 秒、带同步音频的片段。本指南给出了在 hiapi 上可直接使用的请求示例、API 接受和拒绝的字段，以及一次真实运行的结果。你需要从 hiapi 控制台 获取 API 密钥；模型 ID 为 kling-4.0/image-to-video，模型页面 列出了当前规格。

如果你仍在使用 Kling 3.0，Kling 4.0 API 概览 是在发布前写的，描述的是其发布公告；本页面才是当前可用的参考。

最小请求（curl）

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4.0/image-to-video",
    "input": {
      "prompt": "她微微把头转向镜头，头发随风飘动，镜头缓缓推进，环境海浪声",
      "image_urls": ["https://example.com/first-frame.jpg"],
      "duration": 3,
      "resolution": "720p"
    }
  }'

响应会立即返回一个任务 ID：

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

轮询 GET /v1/tasks/<taskId>，直到 data.status 为 success，然后读取 data.output[0].url。

Python：提交与轮询

import os, time, requests

BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def kling4_i2v(image_url, prompt, duration=5, resolution="720p"):
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, json={
        "model": "kling-4.0/image-to-video",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],   # 恰好一张首帧图
            "duration": duration,        # 整数，3-30
            "resolution": resolution,    # "720p" 或 "1080p"
        },
    })
    body = r.json()
    if body["code"] != 200:
        raise RuntimeError(body["message"])
    task_id = body["data"]["taskId"]

    while True:
        d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)

请立即下载返回的 MP4 文件。输出 URL 带有 expireAt 时间戳（在我们的运行中约为七天之后），且托管在临时域名上，因此请将其复制到你自己的存储中，而不要直接热链接。

API 接受的字段

我们用故意无效的值探测了该端点（这些值会返回 HTTP 400 INVALID_REQUEST 且不会创建任务）：

字段	观察到的规则
image_urls	必填数组，恰好一项（两项 → maxItems: got 2, want 1）
duration	整数，最小 3，最大 30。像 "5" 这样的字符串会被拒绝（got string, want integer）
resolution	720p 或 1080p
aspect_ratio	可选：16:9、9:16、1:1、21:9。模型页面称省略时构图跟随源图
prompt	运动描述；我们只在验证器探测中发送过不带该字段的请求，因此将其视为推荐字段

从其他视频模型迁移代码时，有两件事容易出错：

• 字段是 image_urls，不是 image_url。 发送 image_url 会同时报出“缺少必填字段 image_urls”和“不允许额外属性 image_url”。
• 没有音频开关。 audio、generate_audio 和 sound 都会作为额外属性被拒绝。音频始终随画面一起生成；请在提示词中引导音频（上面的示例要求环境海浪声）。

未知字段会被拒绝，而不是被忽略，因此拼写错误会以 400 暴露出来，而不是被静默忽略的设置。

生产环境注意事项

• 优先使用回调而非轮询。 片段生成需要数分钟，因此在创建任务时传入 callback（包含 url 和 when: "final"），并在 webhook 中处理结果；仅将轮询作为后备方案。
• 付费前先验证。 由于无效输入会返回 400 且不会创建任务，请先在自己的代码中检查时长和分辨率；错误请求不花钱，但正确请求会按你要求的每一秒计费。
• 计费按秒且取决于分辨率。 更长的片段和 1080p 费用更高；请查看 定价 获取当前费率，而不要依赖文章中的数字。
• 保存任务 ID。 如果轮询因临时网络错误失败，请重新轮询同一 ID，而不是重新提交，否则会创建并计费第二个片段。

实测运行

我们提交了上述请求：一张竖版首帧图，duration: 3，resolution: "720p"，无 aspect_ratio。

• 每约 10 秒轮询一次时观察到的状态序列：handling → archiving → success。
• 总实际耗时：3 秒片段约 274 秒。handling 约占 255 秒；请按分钟而非秒来规划，并围绕回调进行设计。
• 输出文件（用 ffprobe 检查）：H.264 视频，1280×720，3.04 秒，外加相同时长的 AAC 音频轨道。因此音频是真实嵌入 MP4 的，构图遵循 16:9 源图。

我们未测试：1080p、超过 3 秒的时长，以及非默认的 aspect_ratio 值。这些限制来自 API 验证消息和模型页面，而非生成的输出。

相关页面

• Kling 4.0 图生视频模型页面
• Kling 4.0 文生视频模型页面，适用于没有源图的情况
• Kling 3.0 图生视频模型页面
• 如何使用 Kling 3.0 Turbo 图生视频
• hiapi 定价
• hiapi 文档

常见问题

我可以在 Kling 4.0 图生视频中关闭音频吗？

不能通过请求字段实现。audio、generate_audio 和 sound 均被验证器拒绝。请在提示词中描述你想要的声音（或不想要声音）。

我可以发送多少张输入图片？

一张。image_urls 必须恰好包含一张首帧图。

一个请求需要多长时间？

我们的 3 秒 720p 片段端到端大约耗时 274 秒。生产负载请使用回调。

最长的片段是多久？

API 接受 duration 最大为 30（整数秒），并拒绝更高的值；我们自己只生成了 3 秒的片段。