---
title: "Kling AI: Next-Gen AI Video & AI Image Generator"
source: "https://kling.ai/document-api/apiReference/model/imageToVideo"
author:
published:
created: 2026-04-24
description:
tags:
  - "clippings"
---
## Create Task

POST `/v1/videos/image2video`

```bash
curl --location --request POST 'https://api-singapore.klingai.com/v1/videos/image2video' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "model_name": "kling-v2-6",
    "image": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-2.png",
    "image_tail": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png",
    "prompt": "Camera zooms out, the girl smiles",
    "negative_prompt": "",
    "duration": "5",
    "mode": "pro",
    "sound": "off",
    "callback_url": "",
    "external_task_id": ""
}'
```

200

```json
{
  "code": 0, // Error codes; Specific definitions can be found in "Error Code"
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_info": { // Task creation parameters
      "external_task_id": "string" // Customer-defined task ID
    },
    "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit ms
    "updated_at": 1722769557708 // Task update time, Unix timestamp, unit ms
  }
}
```

💡

Please note that in order to maintain naming consistency, the original model field has been changed to model\_name. Please use this field to specify the model version in the future.  
We maintain backward compatibility. If you continue using the original model field, it will not affect API calls and will be equivalent to the default behavior when model\_name is empty (i.e., calling the V1 model).

### Request Header

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

### Request Body

Model Name

Enum values：kling-v1kling-v1-5kling-v1-6kling-v2-masterkling-v2-1kling-v2-1-masterkling-v2-5-turbokling-v2-6kling-v3

imagestringOptional

Reference Image

- Supports image Base64 encoding or image URL (ensure accessibility)

- Important: When using Base64, do NOT add any prefix like `data:image/png;base64,`. Submit only the raw Base64 string.

- Correct Base64 format:

```
iVBORw0KGgoAAAANSUhEUgAAAAUA...
```

- Incorrect Base64 format (with data: prefix):

```
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...
```

- Supported image formats: `.jpg / .jpeg / .png`

- File size: ≤10MB, dimensions: min 300px, aspect ratio: 1:2.5 ~ 2.5:1

- At least one of `image` or `image_tail` must be provided; both cannot be empty

Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details.

image\_tailstringOptional

Reference Image - End frame control

- Supports image Base64 encoding or image URL (ensure accessibility)

- Important: When using Base64, do NOT add any prefix like `data:image/png;base64,`. Submit only the raw Base64 string.

- Supported image formats: `.jpg / .jpeg / .png`

- File size: ≤10MB, dimensions: min 300px

- At least one of `image` or `image_tail` must be provided; both cannot be empty

- `image_tail`, `dynamic_masks/static_mask`, and `camera_control` are mutually exclusive - only one can be used at a time

Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details.

Whether to generate multi-shot video

When true: the prompt parameter is invalid, and the first/end frame generation is not supported.

When false: the shot\_type and multi\_prompt parameters are invalid

shot\_typestringOptional

Storyboard method

Enum values：customizeintelligence

When multi\_shot is true, this parameter is required

promptstringOptional

Positive text prompt

💡

The Omni model can achieve various capabilities through Prompt with elements, images, videos, and other content:

- Specify elements/images/videos using <<<>>> format, e.g.: <<<element\_1>>>, <<<image\_1>>>, <<<video\_1>>>
- For detailed capabilities, see: [KLING Omni Model User Guide](https://kling.ai/quickstart/klingai-video-o1-user-guide), [Kling VIDEO 3.0 Omni Model User Guide](https://kling.ai/quickstart/klingai-video-3-omni-model-user-guide)

- Cannot exceed 2500 characters

- When multi\_shot is false or shot\_type is intelligence, this parameter must not be empty.

- Use `<<<voice_1>>>` to specify voice, with the sequence matching the voice\_list parameter order

- A video generation task can reference up to 2 voices; when specifying a voice, the sound parameter must be "on"

- The simpler the syntax structure, the better. Example: `The man<<<voice_1>>> said: "Hello"`

- When voice\_list is not empty and prompt references voice ID, the task will be billed as "with specified voice"

Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details.

multi\_promptarrayOptional

Information about each storyboard, such as prompts and duration

Define the shot sequence number, corresponding prompt word, and duration through the index, prompt, and duration parameters, where:

- Supports up to 6 storyboards, with a minimum of 1 storyboard.
- The maximum length of the prompt for each storyboard 512 characters.
- The duration of each storyboard should not exceed the total duration, but should not be less than 1.
- The sum of the durations of all storyboards equals the total duration of the current task.

Load with key:value format as follows:

```json
"multi_prompt":[
{"index":int,"prompt":"string","duration":"5"},
{"index":int,"prompt":"string","duration":"5"}
]
```

When multi\_shot is true and shot\_type is customize, this parameter is required.

element\_listarrayOptional

Reference Element List, based on element ID from element library

- Supports up to 3 reference elements

The elements are categorized into video customization element (named as Video Character Elements) and image customization elements (named as Multi-Image Elements), each with distinct scopes of application. Please exercise caution in distinguishing between them. See [Kling Element Library User Guide](https://kling.ai/quickstart/klingai-element-library-3-user-guide).

- Load with key:value format as follows:

```json
"element_list":[
  { "element_id": long },
  { "element_id": long }
]
```

Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details.

▾Hide child attributes

element\_idlongRequired

Element ID from element library

voice\_listarrayOptional

List of voices referenced when generating videos

- A video generation task can reference up to 2 voices

- When voice\_list is not empty and prompt references voice ID, the task will be billed as "with specified voice"

- voice\_id is returned through the voice customization API, or use system preset voices. See [Custom Voices API](https://kling.ai/document-api/apiReference/model/customVoices); NOT the voice\_id of Lip-Sync API

- element\_list and voice\_list are mutually exclusive and cannot coexist

Example:

```json
"voice_list":[
  {"voice_id":"voice_id_1"},
  {"voice_id":"voice_id_2"}
]
```

The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels)

Whether to generate sound when generating video

Enum values：onoff

The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels)

Flexibility in video generation; higher value means lower model flexibility and stronger relevance to user prompt

- Value range: \[0, 1\]

kling-v2.x models do not support this parameter

Video generation mode

Enum values：stdpro4k

- `std`: Standard Mode, basic mode, cost-effective. The output video resolution is 720P.
- `pro`: Professional Mode, generates videos use longer duration but higher quality video output. The output video resolution is 1080P.
- `4k`: 4K Mode, generates videos use longer duration but higher quality video output. The output video resolution is 4K.

Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details.

static\_maskstringOptional

Static brush mask area (mask image created by user using motion brush)

The "Motion Brush" feature includes Dynamic Brush (dynamic\_masks) and Static Brush (static\_mask)

- Supports image Base64 encoding or image URL (same format requirements as image field)

- Supported image formats: `.jpg / .jpeg / .png`

- Aspect ratio must match the input image (image field), otherwise task will fail

- Resolution of static\_mask and dynamic\_masks.mask must be identical, otherwise task will fail

Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details.

dynamic\_masksarrayOptional

Dynamic brush configuration list

- Can configure multiple groups (up to 6), each containing "mask area" and "motion trajectory" sequence

Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details.

▾Hide child attributes

maskstringRequired

Dynamic brush mask area (mask image created by user using motion brush)

- Supports image Base64 encoding or image URL (same format requirements as image field)

- Supported image formats:.jpg /.jpeg /.png

- Aspect ratio must match the input image (image field), otherwise task will fail

- Resolution of static\_mask and dynamic\_masks.mask must be identical, otherwise task will fail

trajectoriesarrayRequired

Motion trajectory coordinate sequence

- For 5s video, trajectory length ≤77, coordinate count range: \[2, 77\]

- Coordinate system uses bottom-left corner of image as origin

Note 1: More coordinate points = more accurate trajectory. 2 points = straight line between them

Note 2: Trajectory direction follows input order. First coordinate is start point, subsequent coordinates are connected sequentially

▾Hide child attributes

xintRequired

X coordinate of trajectory point (pixel coordinate with image bottom-left as origin)

yintRequired

Y coordinate of trajectory point (pixel coordinate with image bottom-left as origin)

camera\_controlobjectOptional

Camera movement control protocol (if not specified, model will intelligently match based on input text/images)

Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details.

▾Hide child attributes

typestringRequired

Predefined camera movement type

Enum values：simpledown\_backforward\_upright\_turn\_forwardleft\_turn\_forward

- simple: Simple camera movement, can choose one of six options in "config"

- down\_back: Camera descends and moves backward ➡️ Pan down and zoom out. config parameter not required

- forward\_up: Camera moves forward and tilts up ➡️ Zoom in and pan up. config parameter not required

- right\_turn\_forward: Rotate right then move forward ➡️ Right rotation advance. config parameter not required

- left\_turn\_forward: Rotate left then move forward ➡️ Left rotation advance. config parameter not required

configobjectOptional

Contains 6 fields to specify camera movement in different directions

- Required when type is "simple"; leave empty for other types

- Choose only one parameter to be non-zero; rest must be 0

▾Hide child attributes

horizontalfloatOptional

Horizontal movement - camera translation along x-axis

- Value range: \[-10, 10\]. Negative = left, Positive = right

verticalfloatOptional

Vertical movement - camera translation along y-axis

- Value range: \[-10, 10\]. Negative = down, Positive = up

panfloatOptional

Horizontal pan - camera rotation around y-axis

- Value range: \[-10, 10\]. Negative = rotate left, Positive = rotate right

tiltfloatOptional

Vertical tilt - camera rotation around x-axis

- Value range: \[-10, 10\]. Negative = tilt down, Positive = tilt up

rollfloatOptional

Roll - camera rotation around z-axis

- Value range: \[-10, 10\]. Negative = counterclockwise, Positive = clockwise

zoomfloatOptional

Zoom - controls camera focal length change, affects field of view

- Value range: \[-10, 10\]. Negative = longer focal length (narrower FOV), Positive = shorter focal length (wider FOV)

Video duration in seconds

Enum values：3456789101112131415

Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details.

watermark\_infoobjectOptional

Whether to generate watermarked results simultaneously

- Defined by the enabled parameter, format:

```json
"watermark_info": { "enabled": boolean }
```

- true: generate watermarked result, false: do not generate

- Custom watermarks are not currently supported

callback\_urlstringOptional

Callback notification URL for task result. If configured, server will notify when task status changes.

- For specific message schema, see [Callback Protocol](https://kling.ai/document-api/apiReference/callbackProtocol)

external\_task\_idstringOptional

Customized Task ID

- Will not overwrite system-generated task ID, but supports querying task by this ID

- Must be unique within a single user account

## Scenario invocation examples

### Image to video with multi-shot

```bash
curl --location 'https://xxx/v1/videos/image2video' \
--header 'Authorization: Bearer xxx' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "kling-v3",
    "image": "xxx",
    "prompt": "",
    "multi_shot": "true",
    "shot_type": "customize",
    "multi_prompt": [
        {
            "index": 1,
            "prompt": "Two friends talking under a streetlight at night.  Warm glow, casual poses, no dialogue.",
            "duration": "2"
        },
        {
            "index": 2,
            "prompt": "A runner sprinting through a forest, leaves flying.  Low-angle shot, focus on movement.",
            "duration": "3"
        },
        {
            "index": 3,
            "prompt": "A woman hugging a cat, smiling.  Soft sunlight, cozy home setting, emphasize warmth.",
            "duration": "3"
        },
        {
            "index": 4,
            "prompt": "A door creaking open, shadowy hallway.  Dark tones, minimal details, eerie mood.",
            "duration": "3"
        },
        {
            "index": 5,
            "prompt": "A man slipping on a banana peel, shocked expression.  Exaggerated pose, bright colors.",
            "duration": "3"
        },
        {
            "index": 6,
            "prompt": "A sunset over mountains, small figure walking away.  Wide angle, peaceful atmosphere.",
            "duration": "1"
        }
    ],
    "negative_prompt": "",
    "duration": "15",
    "mode": "pro",
    "sound": "on",
    "callback_url": "",
    "external_task_id": ""
}'
```

### Image to video with element

```bash
curl --location 'https://api-singapore.klingai.com/v1/images/generations' \
--header 'Authorization: Bearer xxx' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "kling-v3",
    "prompt": "Merge all the characters from the images into the <<<object_2>>> diagram",
    "element_list": [
        {
            "element_id": "160"
        },
        {
            "element_id": "161"
        },
        {
            "element_id": "159"
        }
    ],
    "image": "xxx",
    "resolution": "2k",
    "n": "9",
    "aspect_ratio": "3:2",
    "external_task_id": "",
    "callback_url": ""
}'
```

```bash
curl --location 'https://xxx/v1/videos/text2video' \
--header 'Authorization: Bearer xxx' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "kling-v3",
    "prompt": "",
    "multi_prompt": [
        {
            "index": 1,
            "prompt": "Two friends talking under a streetlight at night.  Warm glow, casual poses, no dialogue.",
            "duration": "2"
        },
        {
            "index": 2,
            "prompt": "A runner sprinting through a forest, leaves flying.  Low-angle shot, focus on movement.",
            "duration": "3"
        },
        {
            "index": 3,
            "prompt": "A woman hugging a cat, smiling.  Soft sunlight, cozy home setting, emphasize warmth.",
            "duration": "3"
        },
        {
            "index": 4,
            "prompt": "A door creaking open, shadowy hallway.  Dark tones, minimal details, eerie mood.",
            "duration": "3"
        },
        {
            "index": 5,
            "prompt": "A man slipping on a banana peel, shocked expression.  Exaggerated pose, bright colors.",
            "duration": "3"
        },
        {
            "index": 6,
            "prompt": "A sunset over mountains, small figure walking away.  Wide angle, peaceful atmosphere.",
            "duration": "1"
        }
    ],
    "multi_shot": true,
    "shot_type": "customize",
    "duration": "15",
    "mode": "pro",
    "sound": "on",
    "aspect_ratio": "9:16",
    "callback_url": "",
    "external_task_id": ""
}'
```

### Generate video with voice control

```bash
curl --location 'https://api-singapore.klingai.com/v1/videos/image2video/' \
--header 'Authorization: Bearer {Replace your token}' \
--header 'Content-Type: application/json; charset=utf-8' \
--data '{
    "model_name": "kling-v2-6",
    "image": "Replace the URL of image",
    "prompt": "<<<voice_1>>>Ask the people in the picture to say the following words, '\''Welcome everyone'\''",    //If a specific dialogue needs to be enclosed in quotation marks
    "voice_list": [
        {
            "voice_id": "Replace the ID of voice"
        }
    ],
    "duration": "5",
    "mode": "pro",
    "sound": "on",
    "callback_url": "",
    "external_task_id": ""
}'
```

---

## Query Task (Single)

GET `/v1/videos/image2video/{id}`

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

200

```json
{
  "code": 0, // Error codes; Specific definitions can be found in "Error Code"
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed
    "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.)
    "watermark_info": {
      "enabled": boolean
    },
    "task_result": {
      "videos": [
        {
          "id": "string", // Generated video ID; globally unique
          "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
          "watermark_url": "string", // Watermarked video download URL, anti-leech format
          "duration": "string" // Total video duration, unit: s
        }
      ]
    },
    "task_info": { // Task creation parameters
      "external_task_id": "string" // Customer-defined task ID
    },
    "final_unit_deduction": "string", // The deduction units of task
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms
  }
}
```

### Request Header

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

### Path Parameters

task\_idstringOptional

Task ID for image to video

- Request path parameter, fill value directly in request path

- Choose one between task\_id and external\_task\_id for querying

external\_task\_idstringOptional

Customized Task ID for image to video

- The external\_task\_id provided when creating the task

- Choose one between task\_id and external\_task\_id for querying

---

## Query Task (List)

GET `/v1/videos/image2video`

```bash
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/videos/image2video?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'
```

200

```json
{
  "code": 0, // Error codes; Specific definitions can be found in Error codes
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, to track requests and troubleshoot problems
  "data": [
    {
      "task_id": "string", // Task ID, generated by the system
      "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed
      "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.)
      "task_info": { // Task creation parameters
        "external_task_id": "string" // Customer-defined task ID
      },
      "task_result": {
        "videos": [
          {
            "id": "string", // Generated video ID; globally unique
            "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
            "watermark_url": "string", // Watermarked video download URL, anti-leech format
            "duration": "string" // Total video duration, unit: s (seconds)
          }
        ]
      },
      "watermark_info": {
        "enabled": boolean
      },
      "final_unit_deduction": "string", // The deduction units of task
      "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
      "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms
    }
  ]
}
```

### Request Header

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

### Query Parameters

Page number

- Value range: \[1, 1000\]

Data volume per page

- Value range: \[1, 500\]