教程
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 秒的片段。
