Virtual Try-On

Create Task

POST/v1/images/kolors-virtual-try-on

curl --request POST \
  --url https://api-singapore.klingai.com/v1/images/kolors-virtual-try-on \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kolors-virtual-try-on-v1-5",
    "human_image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/tryon-human.webp",
    "cloth_image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/suite.webp",
    "callback_url": "",
    "external_task_id": ""
  }'

200

{
  "code": 0, // Error codes; specific definitions see Error codes
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, for tracking and troubleshooting
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string", // Task status: submitted, processing, succeed, failed
    "created_at": 1722769557708, // Task creation time, Unix timestamp, ms
    "updated_at": 1722769557708 // Task update time, Unix timestamp, ms
  }
}

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Request Body

model_namestringOptionalDefault to kolors-virtual-try-on-v1

Model Name

Enum values：kolors-virtual-try-on-v1kolors-virtual-try-on-v1-5

human_imagestringRequired

Reference human Image

Supports inputting 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

The image file size cannot exceed 10MB, and the width and height dimensions of the image shall not be less than 300px

cloth_imagestringRequired

Reference clothing image

Support uploading clothing product images or clothing image with white background; Supports single clothing (upper, lower, and dress) try-on

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

Base64 Encoding Note:
Please note, if you use the Base64 method, make sure all image data parameters you pass are in Base64 encoding format. When using Base64, do NOT add any prefix like data:image/png;base64,. Only provide the Base64-encoded string.

Correct:

iVBORw0KGgoAAAANSUhEUgAAAAUA...

Incorrect:

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

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

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

The kolors-virtual-try-on-v1-5 model not only supports single clothing input, but also supports "upper + lower" combination input:
- Input a single clothing image (upper, lower, or dress) → Generate a try-on image of the single item
- Input a combination clothing image (merge multiple items into one image with white background):
  - "upper + lower" → Success
  - "upper + upper" → Fails
  - "lower + lower" → Fails
  - "dress + dress" → Fails
  - "upper + dress" → Fails
  - "lower + dress" → Fails

callback_urlstringOptional

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

For the 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

Please note that the customized task ID must be unique within a single user account.

cURL
curl --request POST \
  --url https://api-singapore.klingai.com/v1/images/kolors-virtual-try-on \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kolors-virtual-try-on-v1-5",
    "human_image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/tryon-human.webp",
    "cloth_image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/suite.webp",
    "callback_url": "",
    "external_task_id": ""
  }'
200
{
  "code": 0, // Error codes; specific definitions see Error codes
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, for tracking and troubleshooting
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string", // Task status: submitted, processing, succeed, failed
    "created_at": 1722769557708, // Task creation time, Unix timestamp, ms
    "updated_at": 1722769557708 // Task update time, Unix timestamp, ms
  }
}

Query Task (Single)

GET/v1/images/kolors-virtual-try-on/{id}

curl --request GET \
  --url https://api-singapore.klingai.com/v1/images/kolors-virtual-try-on/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'

200

{
  "code": 0, // Error codes; specific definitions see Error codes
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, for tracking and troubleshooting
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string", // Task status: submitted, processing, succeed, failed
    "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (e.g. content risk control)
    "final_unit_deduction": "string", // The deduction units of task
    "created_at": 1722769557708, // Task creation time, Unix timestamp, ms
    "updated_at": 1722769557708, // Task update time, Unix timestamp, ms
    "task_info": { // Task creation parameters
      "external_task_id": "string" // Customer-defined task ID
    },
    "task_result": {
      "images": [
        {
          "index": 0, // Image Number
          "url": "string" // URL for generating images (To ensure information security, generated images/videos will be cleared after 30 days. Please save them promptly.)
        }
      ]
    }
  }
}

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Path Parameters

idstringRequired

Task ID for virtual try-on. Request path parameter, directly fill the value in the request path.

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/kolors-virtual-try-on/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'
200
{
  "code": 0, // Error codes; specific definitions see Error codes
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, for tracking and troubleshooting
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string", // Task status: submitted, processing, succeed, failed
    "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (e.g. content risk control)
    "final_unit_deduction": "string", // The deduction units of task
    "created_at": 1722769557708, // Task creation time, Unix timestamp, ms
    "updated_at": 1722769557708, // Task update time, Unix timestamp, ms
    "task_info": { // Task creation parameters
      "external_task_id": "string" // Customer-defined task ID
    },
    "task_result": {
      "images": [
        {
          "index": 0, // Image Number
          "url": "string" // URL for generating images (To ensure information security, generated images/videos will be cleared after 30 days. Please save them promptly.)
        }
      ]
    }
  }
}

Query Task (List)

GET/v1/images/kolors-virtual-try-on

curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/images/kolors-virtual-try-on?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'

200

{
  "code": 0, // Error codes; specific definitions see Error codes
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, for tracking and troubleshooting
  "data": [
    {
      "task_id": "string", // Task ID, generated by the system
      "task_status": "string", // Task status: submitted, processing, succeed, failed
      "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (e.g. content risk control)
      "final_unit_deduction": "string", // The deduction units of task
      "created_at": 1722769557708, // Task creation time, Unix timestamp, ms
      "updated_at": 1722769557708, // Task update time, Unix timestamp, ms
      "task_info": { // Task creation parameters
        "external_task_id": "string" // Customer-defined task ID
      },
      "task_result": {
        "images": [
          {
            "index": 0, // Image Number
            "url": "string" // URL for generating images (To ensure information security, generated images/videos will be cleared after 30 days. Please save them promptly.)
          }
        ]
      }
    }
  ]
}

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/images/kolors-virtual-try-on?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'
200
{
  "code": 0, // Error codes; specific definitions see Error codes
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, for tracking and troubleshooting
  "data": [
    {
      "task_id": "string", // Task ID, generated by the system
      "task_status": "string", // Task status: submitted, processing, succeed, failed
      "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (e.g. content risk control)
      "final_unit_deduction": "string", // The deduction units of task
      "created_at": 1722769557708, // Task creation time, Unix timestamp, ms
      "updated_at": 1722769557708, // Task update time, Unix timestamp, ms
      "task_info": { // Task creation parameters
        "external_task_id": "string" // Customer-defined task ID
      },
      "task_result": {
        "images": [
          {
            "index": 0, // Image Number
            "url": "string" // URL for generating images (To ensure information security, generated images/videos will be cleared after 30 days. Please save them promptly.)
          }
        ]
      }
    }
  ]
}