Kling AI Image-to-Video
Overview
Animate static images using the /v1/videos/image2video endpoint. Supports motion prompts, camera control, dynamic masks (motion brush), static masks, and tail images for start-to-end transitions.
Endpoint: POST https://api.klingai.com/v1/videos/image2video
Request Parameters
| Parameter | Type | Required | Description |
|---|
model_name | string | Yes | kling-v1-5, kling-v2-1, kling-v2-master, etc. |
image | string | Yes | URL of the source image (JPG, PNG, WebP) |
prompt | string | No | Motion description for the animation |
negative_prompt | string | No | What to exclude |
duration | string | Yes | "5" or "10" seconds |
aspect_ratio | string | No | "16:9" default |
mode | string | No | "standard" or "professional" |
cfg_scale | float | No | Prompt adherence (0.0-1.0) |
image_tail | string | No | End-frame image URL (mutually exclusive with masks/camera) |
camera_control | object | No | Camera movement (mutually exclusive with masks/image_tail) |
static_mask | string | No | Mask image URL for fixed regions |
dynamic_masks | array | No | Motion brush trajectories |
callback_url | string | No | Webhook for completion |
Basic Image-to-Video
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/", headers=get_headers()
).json()
result[][] == :
()
result[][] == :
RuntimeError(result[][])
Start-to-End Transition (image_tail)
Use image_tail to specify both the first and last frame. Kling interpolates the motion between them.
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",
})
Motion Brush (dynamic_masks)
Draw motion paths for specific elements in the image. Up to 6 motion paths per image in v2.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},
{"x": 0.5, "y": 0.5, "t": 0.5},
{"x": 0.5, "y": 0.3, "t": 1.0},
]
}
],
})
Static Mask (freeze regions)
Keep specific areas of the image static while animating the rest.
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",
})
Mutual Exclusivity Rules
These features cannot be combined in a single request:
| Feature Set A | Feature Set 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 |
Image Requirements
| Constraint | Value |
|---|
| Formats | JPG, PNG, WebP |
| Max size | 10 MB |
| Min resolution | 300x300 px |
| Max resolution | 4096x4096 px |
| Mask format | PNG with white (selected) / black (excluded) |
Error Handling
| Error | Cause | Fix |
|---|
400 invalid image | URL unreachable or wrong format | Verify image URL is publicly accessible |
400 mutual exclusivity | Combined incompatible features | Use only one feature set per request |
task_status: failed | Image too complex or low quality | Use higher resolution, clearer source |
| Mask mismatch | Mask dimensions differ from source | Ensure mask matches source image dimensions |
Resources
