Multi-Image to Image

Create Task

POST/v1/images/multi-image2image

curl --request POST \
  --url https://api-singapore.klingai.com/v1/images/multi-image2image \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v2-1",
    "prompt": "Wearing a flowing red dress on the grassland, in Ghibli style.",
    "negative_prompt": "",
    "subject_image_list": [
      { "subject_image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png" },
      { "subject_image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-2.png" }
    ],
    "scene_image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/background.jpeg",
    "style_image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/16x9_jipuli.png",
    "n": 2,
    "aspect_ratio": "9:16"
  }'

200

{
  "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_info": { //Task creation parameters
      "external_task_id": "string" //User-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
  }
}

Generate images based on multiple reference images (subject, scene, style).

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Request Body

model_namestringOptionalDefault to kling-v2

Model Name

Enum values：kling-v2kling-v2-1

promptstringOptional

Positive text prompt

Cannot exceed 2500 characters

subject_image_listarrayRequired

Subject Reference Images

Support up to 4 images, at least 1 image, using key:value format as follows:

"subject_image_list":[
  { "subject_image":"image_url" },
  { "subject_image":"image_url" },
  { "subject_image":"image_url" },
  { "subject_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 in width and height. Aspect ratio must be between 1:2.5 and 2.5:1

▾Hide child attributes

subject_imagestringRequired

Subject image URL or Base64 string

scene_imagestringOptional

Scene Reference Image

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 in width and height. Aspect ratio must be between 1:2.5 and 2.5:1

style_imagestringOptional

Style Reference Image

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 in width and height. Aspect ratio must be between 1:2.5 and 2.5:1

nintOptionalDefault to 1

Number of generated images

Value range: [1, 9]

aspect_ratiostringOptionalDefault to 16:9

Aspect ratio of the generated images (width:height)

Enum values：16:99:161:14:33:43:22:321:9

The support range for different model versions varies. For details, see Capability Map

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

The callback notification address for the result of this task. If configured, the server will actively notify when the task status changes

The specific message schema of the notification can be found in Callback Protocol

external_task_idstringOptional

Customized Task ID

User-defined task ID. It will not override the system-generated task ID, but supports querying tasks by this ID

Please note that it must be unique for each user

cURL
curl --request POST \
  --url https://api-singapore.klingai.com/v1/images/multi-image2image \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v2-1",
    "prompt": "Wearing a flowing red dress on the grassland, in Ghibli style.",
    "negative_prompt": "",
    "subject_image_list": [
      { "subject_image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png" },
      { "subject_image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-2.png" }
    ],
    "scene_image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/background.jpeg",
    "style_image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/16x9_jipuli.png",
    "n": 2,
    "aspect_ratio": "9:16"
  }'
200
{
  "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_info": { //Task creation parameters
      "external_task_id": "string" //User-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
  }
}

Query Task (Single)

GET/v1/images/multi-image2image/{id}

curl --request GET \
  --url https://api-singapore.klingai.com/v1/images/multi-image2image/{id} \
  --header 'Authorization: Bearer <token>'

200

{
  "code": 0, // Error codes; specific definitions see Error codes
  "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: submitted, processing, succeed, failed
    "task_status_msg": "string", // Task status message, failure reason when task fails
    "final_unit_deduction": "string", // Final unit deduction for the task
    "watermark_info": { "enabled": boolean },
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708, // Task update time, Unix timestamp, unit: ms
    "task_result": {
      "images": [
        {
          "index": 0, // Image number, 0-9
          "url": "string", // URL for generated image (Generated images/videos will be cleared after 30 days. Please save promptly.)
          "watermark_url": "string" // Watermarked image download URL, anti-hotlinking format
        }
      ]
    }
  }
}

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Path Parameters

task_idstringRequired

The task ID for image generation. Request path parameter, directly fill the value in the request path. Query by external_task_id or task_id.

external_task_idstringOptional

Customized Task ID for audio generation

The external_task_id filled in when creating the task. You can choose to query by external_task_id or task_id
When creating a task, you can choose to query by external_task_id or task_id.

cURL
curl --request GET \
  --url https://api-singapore.klingai.com/v1/images/multi-image2image/{id} \
  --header 'Authorization: Bearer <token>'
200
{
  "code": 0, // Error codes; specific definitions see Error codes
  "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: submitted, processing, succeed, failed
    "task_status_msg": "string", // Task status message, failure reason when task fails
    "final_unit_deduction": "string", // Final unit deduction for the task
    "watermark_info": { "enabled": boolean },
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708, // Task update time, Unix timestamp, unit: ms
    "task_result": {
      "images": [
        {
          "index": 0, // Image number, 0-9
          "url": "string", // URL for generated image (Generated images/videos will be cleared after 30 days. Please save promptly.)
          "watermark_url": "string" // Watermarked image download URL, anti-hotlinking format
        }
      ]
    }
  }
}

Query Task (List)

GET/v1/images/multi-image2image

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

200

{
  "code": 0, // Error codes; specific definitions see Error codes
  "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: submitted, processing, succeed, failed
      "task_status_msg": "string", // Task status message
      "final_unit_deduction": "string", // Final unit deduction for the task
      "watermark_info": { "enabled": true },
      "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
      "updated_at": 1722769557708, // Task update time, Unix timestamp, unit: ms
      "task_result": {
        "images": [
          {
            "index": 0, // Image number, 0-9
            "url": "string", // URL for generated image (Generated images/videos will be cleared after 30 days. Please save promptly.)
            "watermark_url": "string" // Watermarked image download URL, anti-hotlinking format
          }
        ]
      }
    }
  ]
}

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

Number of items per page

Value range: [1, 500]

cURL
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/images/multi-image2image?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'
200
{
  "code": 0, // Error codes; specific definitions see Error codes
  "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: submitted, processing, succeed, failed
      "task_status_msg": "string", // Task status message
      "final_unit_deduction": "string", // Final unit deduction for the task
      "watermark_info": { "enabled": true },
      "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
      "updated_at": 1722769557708, // Task update time, Unix timestamp, unit: ms
      "task_result": {
        "images": [
          {
            "index": 0, // Image number, 0-9
            "url": "string", // URL for generated image (Generated images/videos will be cleared after 30 days. Please save promptly.)
            "watermark_url": "string" // Watermarked image download URL, anti-hotlinking format
          }
        ]
      }
    }
  ]
}