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

POST `/v1/videos/multi-elements/init-selection`

```bash
curl --request POST \
  --url https://api-singapore.klingai.com/v1/videos/multi-elements/init-selection \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video_id": "",
    "video_url": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/animals-output-5s.mp4"
  }'
```

200

```json
{
  "code": 0, // Error code; Specific definitions can be found in "Error Code"
  "message": "string", // Error message
  "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting
  "data": {
    "status": 0, // Rejection code, non-zero indicates recognition failure
    "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours
    "final_unit_deduction": "string", // The deduction units of task
    "fps": 30.0, // Frame rate of parsed video, required when fetching selection preview video
    "original_duration": 1000, // Duration of parsed video, required when creating task
    "width": 720, // Width of parsed video, currently unused
    "height": 1280, // Height of parsed video, currently unused
    "total_frame": 300, // Total frame count of parsed video, required when creating task
    "normalized_video": "url" // URL of initialized video
}
```

💡

Initialize the original video before using Multi-elements feature. When replacing or removing elements within the existing video, the relevant elements need to be marked in the video beforehand.

### Request Header

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

### Request Body

video\_idstringOptional

The ID of the video generated by the Kling AI

- Only videos generated within the last 30 days are supported

- Only supports videos with a duration of ≥2 seconds and ≤5 seconds, or ≥7 seconds and ≤10 seconds

video\_urlstringOptional

Get link for uploaded video

- Only.mp4/.mov formats are supported

- Only supports videos with a duration of ≥2 seconds and ≤5 seconds, or ≥7 seconds and ≤10 seconds

- Video resolution must be between 720px and 2160px (inclusive) in both width and height

- Only supports videos with frame rates of 24, 30, or 60 fps

---

## Add Video Selection Area

POST `/v1/videos/multi-elements/add-selection`

```bash
curl --request POST \
  --url https://api-singapore.klingai.com/v1/videos/multi-elements/add-selection \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "session_id": "847570360458960960",
    "frame_index": 0,
    "points": [
      {
        "x": 0.7738498789346246,
        "y": 0.297142857142857
      }
    ]
  }'
```

200

```json
{
  "code": 0, // Error code; Specific definitions can be found in "Error Code"
  "message": "string", // Error message
  "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting
  "data": {
    "status": 0, // Rejection code, non-zero indicates recognition failure
    "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours
    "final_unit_deduction": "string", // The deduction units of task
    "res": {
      "frame_index": 0,
      "rle_mask_list": [{
        "object_id": 0,
        "rle_mask": {
          "size": [720, 1280],
          "counts": "string"
        },
        "png_mask": {
          "size": [720, 1280],
          "base64": "string"
        }
      }]
    }
  }
}
```

### Request Header

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

### Request Body

session\_idstringRequired

Session ID, generated during the video initialization task and remains unchanged during editing operations

frame\_indexintRequired

Frame Number

- A maximum of 10 frames can be marked. That is, up to 10 frames can be used to define selection areas in the video

- Only supports marking 1 frame at a time

pointsarrayRequired

Click Coordinates, represented by x and y

- Value range: \[0, 1\], expressed as percentages; \[0, 1\] represents the top-left corner of the frame

- Multiple points can be marked at once; up to 10 points can be marked on a single frame

▾Hide child attributes

xfloatRequired

X coordinate \[0-1\]

yfloatRequired

Y coordinate \[0-1\]

### Sample Code

#### Decoding Image Segmentation Result

```typescript
export type RLEObject = {
  size: [h: number, w: number]
  counts: string
}
type RLE = {
  h: number
  w: number
  m: number
  binaries: number[]
}
export function decode(rleObj: RLEObject) {
  const [h, w] = rleObj.size
  const R: RLE = { h, w, m: 0, binaries: [0] }
  rleFrString(R, rleObj.counts)
  const unitArray = new Uint8Array(h * w)
  rleDecode(R, unitArray)
  return unitArray
}
function rleDecode(R: RLE, M: Uint8Array) {
  let j
  let k
  let p = 0
  let v = false
  for (j = 0; j < R.m; j++) {
    for (k = 0; k < R.binaries[j]; k++) {
      const x = Math.floor(p / R.h)
      const y = p % R.h
      M[y * R.w + x] = v === false ? 0 : 1 // Note: y * width + x indicates row-major (horizontal) layout.
      p++
    }
    v = !v
  }
}
function rleFrString(R: RLE, s: string) {
  let m = 0
  let p = 0
  let k
  let x
  let more
  const binaries = []
  while (s[p]) {
    x = 0
    k = 0
    more = 1
    while (more) {
      const c = s.charCodeAt(p) - 48
      x |= (c & 0x1f) << (5 * k)
      more = c & 0x20
      p++
      k++
      if (!more && c & 0x10) {
        x |= -1 << (5 * k)
      }
    }
    if (m > 2) {
      x += binaries[m - 2]
    }
    binaries[m++] = x
  }
  R.m = m
  R.binaries = binaries
}
```

#### Rendering the Segmentation Mask Layer

```typescript
// height refers to the video height and width refers to the video width
function drawMask(rleMask: string, height: number, width: number) {
  if (!canvasRef.value) return
  const ctx = canvasRef.value.getContext('2d')
  if (!ctx) return

  const decodeData = decode({ counts: rleMask, size: [height, width] })
  const imageData = ctx.createImageData(width, height)
  for (let y = 0; y < height; y++) {
    for (let x = 0; x < width; x++) {
      const index = y * width + x
      if (decodeData[index]) {
        const imageIndex = index * 4
        // Set pixel color: red, green, blue, alpha
        imageData.data[imageIndex] = 116 // red
        imageData.data[imageIndex + 1] = 255 // green
        imageData.data[imageIndex + 2] = 82 // blue
        imageData.data[imageIndex + 3] = 163 // alpha
      }
    }
  }
  ctx.putImageData(imageData, 0, 0)
}
```

---

## Delete Video Selection Area

POST `/v1/videos/multi-elements/delete-selection`

```bash
curl --request POST \
  --url https://api-singapore.klingai.com/v1/videos/multi-elements/delete-selection \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "session_id": "847570360458960960",
    "frame_index": 0,
    "points": [
      {
        "x": 0.7738498789346246,
        "y": 0.297142857142857
      }
    ]
  }'
```

200

```json
{
  "code": 0, // Error code; Specific definitions can be found in "Error Code"
  "message": "string", // Error message
  "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting
  "data": {
    "status": 0, // Rejection code, non-zero indicates recognition failure
    "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours
    "final_unit_deduction": "string", // The deduction units of task
    "res": {
      "frame_index": 0,
      "rle_mask_list": [{
        "object_id": 0,
        "rle_mask": {
          "size": [720, 1280],
          "counts": "string"
        },
        "png_mask": {
          "size": [720, 1280],
          "base64": "string"
        }
      }]
    }
  }
}
```

### Request Header

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

### Request Body

session\_idstringRequired

Session ID, generated during the video initialization task and remains unchanged during editing operations

frame\_indexintRequired

Frame Number

pointsarrayRequired

Click Coordinates to delete, represented by x and y

- Value range: \[0, 1\], expressed as percentages; \[0, 1\] represents the top-left corner of the frame

- Multiple points can be provided at once

- Coordinates must exactly match those used when adding the video selection area

▾Hide child attributes

xfloatRequired

X coordinate \[0-1\]

yfloatRequired

Y coordinate \[0-1\]

---

## Clear Video Selection

POST `/v1/videos/multi-elements/clear-selection`

```bash
curl --request POST \
  --url https://api-singapore.klingai.com/v1/videos/multi-elements/clear-selection \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "session_id": "847570360458960960"
  }'
```

200

```json
{
  "code": 0, // Error code; Specific definitions can be found in "Error Code"
  "message": "string", // Error message
  "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting
  "data": {
    "status": 0, // Rejection code, non-zero indicates recognition failure
    "session_id": "id" // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours
    "final_unit_deduction": "string", // The deduction units of task
  }
}
```

### Request Header

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

### Request Body

session\_idstringRequired

Session ID, generated during the video initialization task and remains unchanged during editing operations

---

## Preview Video with Selected Areas

POST `/v1/videos/multi-elements/preview-selection`

```bash
curl --request POST \
  --url https://api-singapore.klingai.com/v1/videos/multi-elements/preview-selection \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "session_id": "847570360458960960"
  }'
```

200

```json
{
  "code": 0, // Error code; Specific definitions can be found in "Error Code"
  "message": "string", // Error message
  "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting
  "data": {
    "status": 0, // Rejection code, non-zero indicates recognition failure
    "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours
    "final_unit_deduction": "string", // The deduction units of task
    "res": {
      "video": "url", // Video with mask
      "video_cover": "url", // Cover image of video with mask
      "tracking_output": "url" // Mask result for each frame in image segmentation results
    }
  }
}
```

### Request Header

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

### Request Body

session\_idstringRequired

Session ID, generated during the video initialization task and remains unchanged during editing operations

---

## Create Task

POST `/v1/videos/multi-elements`

```bash
curl --request POST \
  --url https://api-singapore.klingai.com/v1/videos/multi-elements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v1-6",
    "session_id": "847570360458960960",
    "edit_mode": "removal",
    "image_list": [],
    "prompt": "Delete the chick from <<<video_1>>>",
    "negative_prompt": "",
    "mode": "std",
    "duration": "5",
    "callback_url": "",
    "external_task_id": ""
  }'
```

200

```json
{
  "code": 0, // Error code; Specific definitions can be found in "Error Code"
  "message": "string", // Error message
  "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed
    "task_info": {
      "external_task_id": "string" // User-defined task ID
    },
    "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

### Request Body

Model Name

Enum values：kling-v1-6

session\_idstringRequired

Session ID, generated during the video initialization task and remains unchanged during editing operations

edit\_modestringRequired

Operation Type

Enum values：additionswapremoval

- addition: Add an element

- swap: Replace an element

- removal: Remove an element

image\_listarrayOptional

Cropped Reference Images

- For adding video elements: This parameter is required; upload 1–2 images

- For editing (swapping) video elements: This parameter is required; upload 1 image only

- For deleting video elements: This parameter is not required

- Use key:value format as follows:

```json
"image_list":[
  { "image":"image_url" },
  { "image":"image_url" }
]
```

- The API does not perform cropping, please upload images with subjects already cropped

- Supports image input as either Base64-encoded string or URL (ensure the URL is publicly accessible)

- 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

- Image file size must not exceed 10MB. Image dimensions must be at least 300px. Aspect ratio must be between 1:2.5 and 2.5:1

▾Hide child attributes

imagestringRequired

Image URL or Base64 string

promptstringRequired

Positive Prompt

- Use the format <<<xxx>>> to explicitly refer to a specific video or image, such as <<<video\_1>>> or <<<image\_1>>>

- To ensure optimal results, the prompt must include references to the video and image(s) required for the editing

- Must not exceed 2,500 characters

💡

**Recommended Prompt Templates:**

**Adding Elements:**

- EN: Using the context of <<<video\_1>>>, seamlessly add \[x\] from <<<image\_1>>>
- ZH: 基于<<<video\_1>>>中的原始内容，以自然生动的方式，将<<<image\_1>>>中的【】，融入<<<video\_1>>>的【】

**Replacing Elements:**

- EN: swap \[x\] from <<<image\_1>>> for \[x\] from <<<video\_1>>>
- ZH: 使用<<<image\_1>>>中的【】，替换<<<video\_1>>>中的【】

**Removing Elements:**

- EN: Delete \[x\] from <<<video\_1>>>
- ZH: 删除<<<video\_1>>>中的【】

Note: \[x\] or 【】 are placeholders where you should fill in specific content.

negative\_promptstringOptional

Negative Prompt

- Must not exceed 2,500 characters

Video Generation Mode

Enum values：stdpro

- std: Standard mode, basic rendering, cost-effective

- pro: Professional mode, high-quality, enhanced rendering, better video output quality

Video Duration (in seconds)

Enum values：510

- Only 5-second and 10-second videos are supported

- To generate a 5-second video, the input video must be ≥2 seconds and ≤5 seconds

- To generate a 10-second video, the input video must be ≥7 seconds and ≤10 seconds

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 URL for Task Result Notification. If configured, the server will actively send notifications when the task status changes

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

external\_task\_idstringOptional

Custom Task ID

- A user-defined task ID; it will not overwrite the system-generated task ID, but can be used to query the task

- Please ensure uniqueness of the task ID within a single user account

---

## Query Task (Single)

GET `/v1/videos/multi-elements/{id}`

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

200

```json
{
  "code": 0, // Error code; Specific definitions can be found in "Error Code"
  "message": "string", // Error message
  "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting
  "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 message, displays failure reason when task fails (e.g., triggered platform content moderation)
    "task_info": { // Task creation parameters
      "external_task_id": "string" // User-defined task ID
    },
    "task_result": {
      "videos": [
        {
          "id": "string", // Generated video ID, globally unique
          "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours
          "url": "string", // URL of generated video (Note: For security purposes, generated images/videos will be deleted after 30 days, please save them promptly)
          "watermark_url": "string", // Watermarked video download URL, anti-hotlinking format
          "duration": "string" // Total video duration, unit: s
        }
      ]
    },
    "watermark_info": {
      "enabled": boolean
    },
    "final_unit_deduction": "string", // Final unit deduction for the 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 Multi-Elements video editing

- Request path parameter, fill the value directly in the request path

- You can choose to query by external\_task\_id or task\_id

external\_task\_idstringOptional

Custom Task ID for Multi-Elements video editing

- The external\_task\_id filled in when creating the task. You can choose to query by external\_task\_id or task\_id

---

## Query Task (List)

GET `/v1/videos/multi-elements`

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

200

```json
{
  "code": 0, // Error code; Specific definitions can be found in "Error Code"
  "message": "string", // Error message
  "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting
  "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 message, displays failure reason when task fails (e.g., triggered platform content moderation)
      "task_info": { // Task creation parameters
        "external_task_id": "string" // User-defined task ID
      },
      "task_result": {
        "videos": [
          {
            "id": "string", // Generated video ID, globally unique
            "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours
            "url": "string", // URL of generated video (Note: For security purposes, generated images/videos will be deleted after 30 days, please save them promptly)
            "watermark_url": "string", // Watermarked video download URL, anti-hotlinking format
            "duration": "string" // Total video duration, unit: s
          }
        ]
      },
      "watermark_info": {
        "enabled": boolean
      },
      "final_unit_deduction": "string", // Final unit deduction for the 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\]

Number of items per page

- Value range: \[1, 500\]