> ## Documentation Index
>
> Fetch the complete documentation index at: https://kling.ai/document-api/llms.txt
> Use this file to discover all available pages before exploring further.

# Virtual Try-On

> Source: https://kling.ai/document-api/api/image/virtual-try-on
> Locale: en
> Current Tab: Virtual Try-On
> This content is optimized for LLMs. In-page tabs are expanded and UI-only controls are omitted.

---

> This capability will be retired on September 15, 2026. For Virtual Try-On use cases, we recommend [Kling Image 3.0 & 3.0 Omni](https://kling.ai/document-api/api/image/3-0-omni/image-generation) as alternatives. A next-generation virtual try-on experience is currently under development, and further updates will be shared as they become available.

## Create Task

### API Overview

- Method: `POST`
- Path: `/v1/images/kolors-virtual-try-on`
- Auth: `Authorization: Bearer <API_KEY>`
- Content-Type: `application/json`

### Description

> When calling the virtual try-on API, charges will be deducted from your dedicated Virtual Try-on Resource Packages or account balance. Image Resource Packages cannot be used to call virtual try-on API

### Headers

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format |
| `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication |

### Request Body

| Field Path | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `model_name` | string | No | `kolors-virtual-try-on-v1` | `kolors-virtual-try-on-v1`, `kolors-virtual-try-on-v1-5` | Model Name |
| `human_image` | string | Yes | - | - | Reference human Image |
| `cloth_image` | string | Yes | - | - | Reference clothing image |
| `callback_url` | string | No | - | - | The callback notification address for the result of this task. If configured, the server will actively notify when the task status changes. |
| `external_task_id` | string | No | - | - | Customized Task ID |

#### Request Body Field Notes

- `human_image`: Supports inputting image Base64 encoding or image URL (ensure accessibility)
- `human_image`: Important: When using Base64, do NOT add any prefix like `data:image/png;base64,`. Submit only the raw Base64 string.
- `human_image`: Correct Base64 format:
  ```plaintext
  iVBORw0KGgoAAAANSUhEUgAAAAUA...
  ```
- `human_image`: Incorrect Base64 format (with data: prefix):
  ```plaintext
  data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...
  ```
- `human_image`: Supported image formats: .jpg / .jpeg / .png
- `human_image`: The image file size cannot exceed 10MB, and the width and height dimensions of the image shall not be less than 300px
- `cloth_image`: Support uploading clothing product images or clothing image with white background; Supports single clothing (upper, lower, and dress) try-on
- `cloth_image`: Supports inputting image Base64 encoding or image URL (ensure accessibility)
- `cloth_image`: 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:
  ```plaintext
  iVBORw0KGgoAAAANSUhEUgAAAAUA...
  ```
  
  Incorrect:
  ```plaintext
  data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...
  ```
- `cloth_image`: Supported image formats: .jpg / .jpeg / .png
- `cloth_image`: File size: ≤10MB, dimensions: min 300px
- `cloth_image`: 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
  
  ![](https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-api-document/try-on.jpeg)
- `callback_url`: For the specific message schema, see [Callback Protocol](https://kling.ai/document-api/api/get-started/callbacks)
- `external_task_id`: Will not overwrite system-generated task ID, but supports querying task by this ID
- `external_task_id`: Please note that the customized task ID must be unique within a single user account.

### Request Example

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

### Response Example

```json
{
  "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)

### API Overview

- Method: `GET`
- Path: `/v1/images/kolors-virtual-try-on/{id}`
- Auth: `Authorization: Bearer <API_KEY>`
- Content-Type: `application/json`

### Headers

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format |
| `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication |

### Path Params

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `id` | string | Yes | - | - | Task ID for virtual try-on. Request path parameter, directly fill the value in the request path. |
| `external_task_id` | string | No | - | - | Customized Task ID for audio generation |

#### Path Params Field Notes

- `external_task_id`: 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.

### Request Example

```bash
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'
```

### Response Example

```json
{
  "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
    "final_balance_deduction": { // Balance deduction information
      "quota": "string", // Balance deduction discount price
      "list_price": "string" // Balance deduction list price
    },
    "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)

### API Overview

- Method: `GET`
- Path: `/v1/images/kolors-virtual-try-on`
- Auth: `Authorization: Bearer <API_KEY>`
- Content-Type: `application/json`

### Headers

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format |
| `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication |

### Query Params

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `pageNum` | int | No | `1` | - | Page number |
| `pageSize` | int | No | `30` | - | Data volume per page |

#### Query Params Field Notes

- `pageNum`: Value range: [1, 1000]
- `pageSize`: Value range: [1, 500]

### Request Example

```bash
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'
```

### Response Example

```json
{
  "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
      "final_balance_deduction": { // Balance deduction information
        "quota": "string", // Balance deduction discount price
        "list_price": "string" // Balance deduction list price
      },
      "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.)
          }
        ]
      }
    }
  ]
}
```