Image to Video

Create Task

POST/v1/videos/image2video

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

{
  "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

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Request Body

model_namestringOptionalDefault to kling-v1

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 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 for details.

multi_shotbooleanOptionalDefault to false

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, Kling VIDEO 3.0 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 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:

"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.

negative_promptstringOptional

Negative text prompt

Cannot exceed 2500 characters

It is recommended to supplement negative prompt via negative sentences within positive prompts

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.

Load with key:value format as follows:

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

Support varies by model version and video mode. See Capability Map 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; NOT the voice_id of Lip-Sync API

element_list and voice_list are mutually exclusive and cannot coexist

Example:

"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

soundstringOptionalDefault to off

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

cfg_scalefloatOptionalDefault to 0.5

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

modestringOptionalDefault to std

Video generation mode

Enum values：stdpro

std: Standard Mode - basic mode, cost-effective

pro: Professional Mode (High Quality) - high performance mode, better video quality

Support varies by model version and video mode. See Capability Map 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 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 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 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)

durationstringOptionalDefault to 5

Video duration in seconds

Enum values：3456789101112131415

Support varies by model version and video mode. See Capability Map for details.

watermark_infoobjectOptional

Whether to generate watermarked results simultaneously

Defined by the enabled parameter, format:

  "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

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

cURL
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
{
  "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
  }
}

Scenario invocation examples

Image to video with multi-shot

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

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": ""
}'

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

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}

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

200

{
  "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

Content-TypestringRequiredDefault to application/json

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

cURL
curl --request GET \
  --url https://api-singapore.klingai.com/v1/videos/image2video/{task_id} \
  --header 'Authorization: Bearer <token>'
200
{
  "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
  }
}

Query Task (List)

GET/v1/videos/image2video

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

200

{
  "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

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Query Parameters

pageNumintOptionalDefault to 1

Page number

Value range: [1, 1000]

pageSizeintOptionalDefault to 30

Data volume per page

Value range: [1, 500]

cURL
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/videos/image2video?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'
200
{
  "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
    }
  ]
}