Kling AI 圖片轉影片
概述
使用 /v1/videos/image2video 端點將靜態圖片動畫化。支援運動提示、相機控制、動態遮罩(motion brush)、靜態遮罩,以及用於首尾轉場的尾幀圖片。
端點: POST https://api.klingai.com/v1/videos/image2video
請求參數
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
model_name | 字串 | 是 | kling-v1-5、kling-v2-1、kling-v2-master 等 |
image | 字串 | 是 | 來源圖片的 URL(JPG、PNG、WebP) |
prompt | 字串 | 否 | 動畫的動作描述 |
negative_prompt | 字串 | 否 | 要排除的內容 |
duration | 字串 | 是 | "5" 或 "10" 秒 |
aspect_ratio | 字串 | 否 | 預設為 "16:9" |
mode | 字串 | 否 | "standard" 或 "professional" |
cfg_scale | 浮點數 | 否 | 提示遵循度(0.0-1.0) |
image_tail | 字串 | 否 | 結束幀圖片 URL(與遮罩/相機互斥) |
camera_control | 物件 | 否 | 相機運動(與遮罩/image_tail 互斥) |
static_mask | 字串 | 否 | 固定區域的遮罩圖片 URL |
dynamic_masks | 陣列 | 否 | 動態畫刷軌跡 |
callback_url | 字串 | 否 | 完成通知的 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": "雲朵在天空中緩緩飄移,微風吹拂樹林",
"negative_prompt": "靜止、凍結、模糊",
"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"影片:{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": "太陽在天空中移動的縮時攝影",
"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": "人物自然向前行走",
"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": "河水在河中流淌,鳥兒飛翔",
"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
請勿替換為真實客戶照片,或在記錄同意書、政策、品質和負責人核准之前發佈金絲雀。