Kling AI 图像转视频 是做什么的?
概述
使用 /v1/videos/image2video 端点将静态图像动画化。支持运动提示、相机控制、动态遮罩(运动笔刷)、静态遮罩以及用于起始到结束过渡的尾部图像。
端点: POST https://api.klingai.com/v1/videos/image2video
请求参数
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
model_name | string | 是 | kling-v1-5, kling-v2-1, kling-v2-master 等 |
image | string | 是 | 源图像的 URL(JPG、PNG、WebP) |
prompt | string | 否 | 动画的运动描述 |
negative_prompt | string | 否 | 要排除的内容 |
duration | string | 是 | "5" 或 "10" 秒 |
aspect_ratio | string | 否 | 默认 "16:9" |
mode | string | 否 | "standard" 或 "professional" |
cfg_scale | float | 否 | 提示词遵循度(0.0-1.0) |
image_tail | string | 否 | 结束帧图像 URL(与遮罩/相机互斥) |
camera_control | object | 否 | 相机移动(与遮罩/image_tail 互斥) |
static_mask | string | 否 | 固定区域的遮罩图像 URL |
dynamic_masks | array | 否 | 运动笔刷轨迹 |
callback_url | string | 否 | 完成通知的 Webhook |
基本图像转视频
import jwt, time, os, requests
BASE = "https://api.klingai.com/v1"
def get_headers():
ak, sk = os.environ["KLING_ACCESS_KEY"], os.environ["KLING_SECRET_KEY"]
token = jwt.encode(
{"iss": ak, "exp": int(time.time()) + 1800, "nbf": int(time.time()) - 5},
sk, algorithm="HS256", headers={"alg": "HS256", "typ": "JWT"}
)
return {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
# 将风景照片动画化
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-1",
"image": "https://example.com/landscape.jpg",
"prompt": "Clouds slowly drifting across the sky, gentle wind rustling through trees",
"negative_prompt": "static, frozen, blurry",
"duration": "5",
"mode": "standard",
})
task_id = response.json()["data"]["task_id"]
# 轮询获取结果
while True:
time.sleep(15)
result = requests.get(
f"{BASE}/videos/image2video/{task_id}", headers=get_headers()
).json()
if result["data"]["task_status"] == "succeed":
print(f"Video: {result['data']['task_result']['videos'][0]['url']}")
break
elif result["data"]["task_status"] == "failed":
raise RuntimeError(result["data"]["task_status_msg"])
起始到结束过渡(image_tail)
使用 image_tail 指定第一帧和最后一帧。Kling 会在它们之间插值运动。
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-master",
"image": "https://example.com/sunrise.jpg", # 第一帧
"image_tail": "https://example.com/sunset.jpg", # 最后一帧
"prompt": "Time lapse of sun moving across the sky",
"duration": "5",
"mode": "professional",
})
运动笔刷(dynamic_masks)
为图像中的特定元素绘制运动路径。在 v2.6 中,每张图像最多支持 6 个运动路径。
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-6",
"image": "https://example.com/person-standing.jpg",
"prompt": "Person walking forward naturally",
"duration": "5",
"dynamic_masks": [
{
"mask": "https://example.com/person-mask.png", # 白色 = 选中的区域
"trajectories": [
{"x": 0.5, "y": 0.7, "t": 0.0}, # 起始位置(归一化 0-1)
{"x": 0.5, "y": 0.5, "t": 0.5}, # 中间点
{"x": 0.5, "y": 0.3, "t": 1.0}, # 结束位置
]
}
],
})
静态遮罩(冻结区域)
在动画化其余部分时,保持图像的特定区域静止。
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-master",
"image": "https://example.com/scene.jpg",
"prompt": "Water flowing in the river, birds flying",
"duration": "5",
"static_mask": "https://example.com/buildings-mask.png", # 白色 = 冻结
})
互斥规则
以下功能不能在单个请求中组合使用:
| 特性集 A | 特性集 B |
|---|---|
image_tail | dynamic_masks, static_mask, camera_control |
dynamic_masks / static_mask | image_tail, camera_control |
camera_control | image_tail, dynamic_masks, static_mask |
图像要求
| 约束 | 值 |
|---|---|
| 格式 | JPG, PNG, WebP |
| 最大大小 | 10 MB |
| 最小分辨率 | 300x300 px |
| 最大分辨率 | 4096x4096 px |
| 遮罩格式 | PNG(白色为选中区域,黑色为排除区域) |
错误处理
| 错误 | 原因 | 修复 |
|---|---|---|
400 无效图像 | URL 无法访问或格式错误 | 验证图像 URL 可公开访问 |
400 互斥 | 组合了不兼容的特性 | 每个请求仅使用一个特性集 |
task_status: failed | 图像过于复杂或质量低 | 使用更高分辨率、更清晰的源图像 |
| 遮罩不匹配 | 遮罩尺寸与源图像不同 | 确保遮罩与源图像尺寸匹配 |
前提条件
- Kling API 凭据存储在运行时密钥管理器中,已批准的模型和时长白名单,以及每个作业的信用额度预算。
- 合成或版权清晰的源图像以及任何遮罩或尾部图像,对于可识别的人物需记录同意,并获得转换资产的许可。
- 私有暂存存储桶和审查负责人。新生成的图像在记录政策、质量和出版批准之前,必须保持草稿状态并带有水印。
说明
- 从已批准的白名单中解析源图像和遮罩引用;拒绝来自不可信 URL、缺少来源证明或包含未记录同意的可识别人物的资产。
- 在花费信用额度之前,验证格式、尺寸、功能互斥性、提示词长度和请求的时长。使用合成固定装置进行自动化检查。
- 使用稳定的作业密钥对请求进行去重,仅在内容策略检查通过后提交,并将任务和源图像保存在私有暂存存储中。
- 运行一个简短的、带水印的沙箱示例。检查运动、策略结果、源图像保真度和信用额度预算,然后再请求负责人批准更大规模或公开的渲染。
- 批准后,按摘要推广确切的任务结果。若失败或撤回,则停止下游发布,删除暂存媒体和临时 URL,并恢复先前批准的资产或作业状态。
- 记录一份隐私处理过的收据,仅包含不透明的作业和资产摘要、策略和批准结果、预算结果、保留期限以及回滚引用。
输出
返回包含不透明任务标识符、模型和时长、状态、输出摘要或私有暂存 URL、示例/批准状态以及清理或回滚引用的结果。不要将源图像、遮罩 URL、提示词、面部数据、凭据或未编辑的提供商响应放入日志或收据中。
示例
对于安全的自动化检查,使用合成的风景固定装置和私有示例:
source=fixture:synthetic-landscape-v3; rights=cleared; mode=standard;
duration=5; canary=watermarked-sandbox; policy=pass; approval=pending;
publish=false; contacts_exported=0; receipt=asset-sha256:opaque
在记录同意、策略、质量和所有者批准之前,请勿替换真实客户的照片或发布示例。