---
title: "Kling AI Image-to-Video API Reference"
aliases: [kling-i2v, kling-image2video, kling-img2vid]
tags: [kling, ai-video, api, image-to-video, video-generation, motion-brush]
sources: [raw/Kling AI Next-Gen AI Video & AI Image Generator 2.md]
created: 2026-04-26
updated: 2026-04-26
---

## Overview

Kling AI's image-to-video endpoint animates a reference image (or interpolates between two images) into a video. Base URL: `https://api-singapore.klingai.com`. Auth via Bearer token.

Companion to [[wiki/web-agency/kling-text-to-video-api|Kling Text-to-Video API]]. Used in the [[wiki/web-agency/claude-code-nanobanana-website-workflow|Claude Code + Nanobanana 2 Website Workflow]] to animate hero images.

---

## Create Task — `POST /v1/videos/image2video`

### Minimal Example

```bash
curl -X POST https://api-singapore.klingai.com/v1/videos/image2video \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model_name": "kling-v2-6",
    "image": "https://example.com/start-frame.png",
    "prompt": "Camera zooms out, the girl smiles",
    "duration": "5",
    "mode": "pro",
    "sound": "off"
  }'
```

### Image Parameters

| Parameter | Notes |
|-----------|-------|
| `image` | Start frame — URL or raw Base64 (no `data:image/png;base64,` prefix). `.jpg/.jpeg/.png`, ≤10MB, min 300px, aspect ratio 1:2.5–2.5:1 |
| `image_tail` | End frame — same format. Mutually exclusive with `dynamic_masks` and `camera_control` |

- At least one of `image` or `image_tail` must be provided.

### Shared Parameters (same as text2video)

| Parameter | Type | Notes |
|-----------|------|-------|
| `model_name` | string | `kling-v1`, `kling-v1-5`, `kling-v1-6`, `kling-v2-master`, `kling-v2-1`, `kling-v2-1-master`, `kling-v2-5-turbo`, `kling-v2-6`, `kling-v3` |
| `prompt` | string | Max 2500 chars. Required unless `multi_shot=true` + `shot_type=intelligence` |
| `negative_prompt` | string | What to avoid |
| `mode` | enum | `std` (720p), `pro` (1080p), `4k` |
| `duration` | enum | 3–15 seconds |
| `sound` | enum | `on` / `off` |
| `cfg_scale` | float | `[0,1]` — not supported on kling-v2.x |
| `callback_url` | string | Webhook on status change |
| `external_task_id` | string | Your own unique ID |

---

## Image-to-Video Exclusive Features

### Start + End Frame Interpolation

Provide both `image` (start) and `image_tail` (end) — Kling generates the transition:

```json
{
  "model_name": "kling-v2-6",
  "image": "https://example.com/frame-start.png",
  "image_tail": "https://example.com/frame-end.png",
  "prompt": "smooth transition",
  "duration": "5",
  "mode": "pro"
}
```

`image_tail` is mutually exclusive with `dynamic_masks` and `camera_control`.

---

### Motion Brush

Control which areas of the image move (dynamic) or stay static.

**Static mask** — areas that should NOT move:
```json
"static_mask": "<base64_or_url>"
```

**Dynamic masks** — areas that should move with a defined trajectory (up to 6 groups):
```json
"dynamic_masks": [
  {
    "mask": "<base64_or_url>",
    "trajectories": [
      { "x": 100, "y": 200 },
      { "x": 300, "y": 400 }
    ]
  }
]
```

- Coordinate origin: **bottom-left** corner of the image
- Trajectory direction: first point = start, subsequent points connected in order
- For 5s video: max 77 trajectory points
- `static_mask` and `dynamic_masks.mask` must have identical resolution
- Mask aspect ratio must match input `image`

---

### Voice Control

Embed a voice into the generated video using `voice_list` + `<<<voice_1>>>` in the prompt:

```json
{
  "model_name": "kling-v2-6",
  "image": "<url>",
  "prompt": "<<<voice_1>>>Ask the people in the picture to say 'Welcome everyone'",
  "voice_list": [{ "voice_id": "<voice_id>" }],
  "sound": "on",
  "duration": "5",
  "mode": "pro"
}
```

- Max 2 voices per task; reference as `<<<voice_1>>>`, `<<<voice_2>>>`
- `sound` must be `"on"` when using voice
- `voice_list` and `element_list` are mutually exclusive
- `voice_id` comes from Custom Voices API (not the Lip-Sync API voice\_id)

---

### Element Library

Reference Kling's element library IDs to apply style/character elements (up to 3):

```json
"element_list": [
  { "element_id": 160 },
  { "element_id": 161 }
]
```

- Two categories: **Video Character Elements** and **Multi-Image Elements** — scopes differ
- Mutually exclusive with `voice_list`
- Reference elements in prompt with `<<<element_1>>>` syntax

---

### Multi-Shot (Storyboard) from Image

```json
{
  "model_name": "kling-v3",
  "image": "<start_frame_url>",
  "multi_shot": true,
  "shot_type": "customize",
  "multi_prompt": [
    { "index": 1, "prompt": "Two friends under a streetlight", "duration": "2" },
    { "index": 2, "prompt": "Runner sprinting through forest", "duration": "3" },
    { "index": 6, "prompt": "Sunset over mountains", "duration": "1" }
  ],
  "duration": "15",
  "mode": "pro",
  "sound": "on"
}
```

- When `multi_shot: true`, the top-level `prompt` is ignored
- First/end frame not supported in multi-shot mode
- `shot_type: "customize"` requires `multi_prompt`; `shot_type: "intelligence"` auto-splits

---

## Query Task

### Single — `GET /v1/videos/image2video/{task_id}`

```bash
curl https://api-singapore.klingai.com/v1/videos/image2video/{task_id} \
  -H 'Authorization: Bearer <token>'
```

Also queryable by `external_task_id` via query param.

### List — `GET /v1/videos/image2video?pageNum=1&pageSize=30`

Pagination: `pageNum` `[1–1000]`, `pageSize` `[1–500]`.

### Response Shape

```json
{
  "data": {
    "task_id": "string",
    "task_status": "succeed",
    "task_result": {
      "videos": [{
        "id": "string",
        "url": "string",
        "watermark_url": "string",
        "duration": "5"
      }]
    },
    "final_unit_deduction": "string"
  }
}
```

Task statuses: `submitted` → `processing` → `succeed` / `failed`

**Videos expire after 30 days — download immediately.**

---

## Key Takeaways

- **Image-to-video** animates a still image; providing both `image` + `image_tail` interpolates between two frames.
- **Motion brush** lets you paint which regions move (dynamic\_masks) vs stay locked (static\_mask). Coordinates use bottom-left origin.
- **Voice injection**: use `<<<voice_1>>>` in prompt + `voice_list` with `sound: "on"`. Max 2 voices.
- **Base64 images**: omit the `data:image/png;base64,` prefix — raw string only.
- **Mutual exclusivity**: `image_tail` / `dynamic_masks` / `camera_control` can't coexist; `voice_list` / `element_list` can't coexist.
- `cfg_scale` not supported on v2.x models.
- Use `model_name` field (not legacy `model`); old field defaults to v1.

---

## Sources

- Raw: `Kling AI Next-Gen AI Video & AI Image Generator 2.md`
- Kling API docs: `https://kling.ai/document-api/apiReference/model/imageToVideo`
