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": "雲が空をゆっくりと流れ、優しい風が木々をそよがせる",
"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 相互排他 | 互換性のない機能を組み合わせた | リクエストごとに1つの機能セットのみを使用 |
task_status: failed | 画像が複雑すぎる、または品質が低い | より高解像度で鮮明なソースを使用 |
| マスク不一致 | マスクの寸法がソースと異なる | マスクがソース画像の寸法と一致することを確認 |
前提条件
- ランタイムシークレットマネージャーに保存されたKling API認証情報、承認済みのモデルと期間許可リスト、およびジョブごとのクレジット予算。
- 合成または権利処理済みのソース画像、および任意のマスクまたはテール画像。識別可能な人物に対する同意の記録と、アセットの変換許可が必要。
- プライベートステージングバケットとレビュー担当者。新しい生成物は、ポリシー、品質、公開の承認が記録されるまで、ドラフトのみで透かし入りとすること。
手順
- 承認済み許可リストからソースとマスクの参照を解決する。信頼できないURL、出典不明のアセット、文書化された同意なしに識別可能な人物を含むアセットは拒否する。
- クレジットを使用する前に、フォーマット、寸法、機能の相互排他性、プロンプトの長さ、要求された期間を検証する。自動チェックには合成フィクスチャを使用する。
- 安定したジョブキーを使用してリクエストの重複を排除し、コンテンツポリシーチェックに合格した場合のみ送信する。タスクとソースはプライベートステージングストレージに保持する。
- 短く透かし入りのサンドボックスカナリアを1回実行する。大規模または公開レンダリングの所有者承認を要求する前に、モーション、ポリシー結果、ソースの忠実性、クレジット予算を確認する。
- 承認後、ダイジェストによって正確なタスク結果をプロモートする。失敗または撤回時は、下流の公開を停止し、ステージングされたメディアと一時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
同意、ポリシー、品質、所有者の承認がすべて記録されるまで、実際の顧客の写真を代用したり、カナリアを公開したりしないでください。