Appy Pie’s Virtual Try-On API allows you to overlay garments onto a background image, enabling a seamless virtual fitting experience. This guide provides all the necessary details to integrate, authenticate, and effectively use the API.

Authentication:

To access this Kolors Virtual-Try-On API, you must subscribe and acquire an Subscription Key. Include this key in the request header to authenticate and gain access.

Request Headers:

Content-Type	Set to application/json
Cache-Control	Recommended to set to no-cache
Ocp-Apim-Subscription-Key	YOUR_SUBSCRIPTION_KEY

Endpoint

Base URL: https://gateway.appypie.com/kling-ai-vton/v1/getVirtualTryOnTask

Request Body Parameters

API Parameters: The API POST- https://gateway.appypie.com/kling-ai-vton/v1/getVirtualTryOnTask takes the following parameters:

Parameters	Type	Required	Description
human_image	string	Yes	Accepts a Base64-encoded string or image URL (e.g., https://storage.googleapis.com/imagesai.appypie.com/testing/00034_00.jpg). For Base64, submit the string without prefixes like data:image/png;base64.
image_tail	string	optional	Defaults to null. Accepts a Base64-encoded string or image URL. Similar to human_image, avoid prefixes when using Base64.
callback_url	string	optional	Defaults to None. A callback URL for task status updates. If provided, the server sends notifications when the task status changes. See "Callback Protocol" for details.

Example Request Body

JSON

{
    "human_image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_human.jpg",
    "cloth_image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_top.jpeg",
    "callback_url": ""
}

Request Code

Input

POST https://gateway.appypie.com/kling-ai-vton/v1/getVirtualTryOnTask HTTP/1.1

Content-Type: application/json
Cache-Control: no-cache

{
    "human_image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_human.jpg",
    "cloth_image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_top.jpeg",
    "callback_url": ""
}

import urllib.request, json

try:
    url = "https://gateway.appypie.com/kling-ai-vton/v1/getVirtualTryOnTask"

    hdr ={
    # Request headers
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache',
    }

    # Request body
    data =  
    data = json.dumps(data)
    req = urllib.request.Request(url, headers=hdr, data = bytes(data.encode("utf-8")))

    req.get_method = lambda: 'POST'
    response = urllib.request.urlopen(req)
    print(response.getcode())
    print(response.read())
    except Exception as e:
    print(e)

// Request body
const body = {
    "human_image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_human.jpg",
    "cloth_image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_top.jpeg",
    "callback_url": ""
};

fetch('https://gateway.appypie.com/kling-ai-vton/v1/getVirtualTryOnTask', {
        method: 'POST',
        body: JSON.stringify(body),
        // Request headers
        headers: {
            'Content-Type': 'application/json',
            'Cache-Control': 'no-cache',}
    })
    .then(response => {
        console.log(response.status);
        console.log(response.text());
    })
    .catch(err => console.error(err));

curl -v -X POST "https://gateway.appypie.com/kling-ai-vton/v1/getVirtualTryOnTask" -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data-raw "{
    \"human_image\": \"https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_human.jpg\",
    \"cloth_image\": \"https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_top.jpeg\",
    \"callback_url\": \"\"
}"

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.util.HashMap;
import java.util.Map;
import java.io.UnsupportedEncodingException;
import java.io.DataInputStream;
import java.io.InputStream;
import java.io.FileInputStream;

public class HelloWorld {

  public static void main(String[] args) {
    try {
        String urlString = "https://gateway.appypie.com/kling-ai-vton/v1/getVirtualTryOnTask";
        URL url = new URL(urlString);
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();

        //Request headers
    connection.setRequestProperty("Content-Type", "application/json");
    
    connection.setRequestProperty("Cache-Control", "no-cache");
    
        connection.setRequestMethod("POST");

        // Request body
        connection.setDoOutput(true);
        connection
            .getOutputStream()
            .write(
             "{ \"human_image\": \"https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_human.jpg\", \"cloth_image\": \"https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_top.jpeg\", \"callback_url\": \"\" }".getBytes()
             );
    
        int status = connection.getResponseCode();
        System.out.println(status);

        BufferedReader in = new BufferedReader(
            new InputStreamReader(connection.getInputStream())
        );
        String inputLine;
        StringBuffer content = new StringBuffer();
        while ((inputLine = in.readLine()) != null) {
            content.append(inputLine);
        }
        in.close();
        System.out.println(content);

        connection.disconnect();
    } catch (Exception ex) {
      System.out.print("exception:" + ex.getMessage());
    }
  }
}

$url = "https://gateway.appypie.com/kling-ai-vton/v1/getVirtualTryOnTask";
$curl = curl_init($url);

curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

# Request headers
$headers = array(
    'Content-Type: application/json',
    'Cache-Control: no-cache',);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

# Request body
$request_body = '{
    "human_image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_human.jpg",
    "cloth_image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_top.jpeg",
    "callback_url": ""
}';
curl_setopt($curl, CURLOPT_POSTFIELDS, $request_body);

$resp = curl_exec($curl);
curl_close($curl);
var_dump($resp);

Get API Key

Response

JSON

HTTP/1.1 200 OK

{
    "code": 0,
    "message": "SUCCEED",
    "request_id": "ChBRS2c7DlgAAAAAAAIzCw",
    "data": {
        "task_id": "ChBRS2c7DlgAAAAAAXXXX",
        "task_status": "submitted",
        "created_at": 1731928289693,
        "updated_at": 1731928289693
    }
}

Next Step: Polling Results

Retrieving Image Status and URL

To verify the completion status of your image request and retrieve the image URL, make a follow-up API call using the task_id provided in the initial response.

Polling Endpoint

Base URL: https://gateway.appypie.com/lumalabs-ai-polling/v1/getStatus

Request Headers:

Content-Type	Set to application/json
Cache-Control	Recommended to set to no-cache

Request Body Parameters

API Parameters: The API POST- https://gateway.appypie.com/kling-ai-polling/v1/getVirtualTryOnStatus takes the following parameters:

Parameters	Type	Required	Description
task_id	string	Yes	A task_id is a unique identifier provided by the Kolors Virtual Try-On API in the initial response to track the progress of your request.

Request Body

Pass the task_id received from the initial response in your request body.

Example Request Body

JSON

{
    "task_id":"task_id"
}

Request Code

Input

POST https://gateway.appypie.com/kling-ai-polling/v1/getVirtualTryOnStatus HTTP/1.1

Content-Type: application/json
Cache-Control: no-cache

{
    "task_id": "task_id"
}

import urllib.request, json

try:
    url = "https://gateway.appypie.com/kling-ai-polling/v1/getVirtualTryOnStatus"

    hdr ={
    # Request headers
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache',
    }

    # Request body
    data =  
    data = json.dumps(data)
    req = urllib.request.Request(url, headers=hdr, data = bytes(data.encode("utf-8")))

    req.get_method = lambda: 'POST'
    response = urllib.request.urlopen(req)
    print(response.getcode())
    print(response.read())
    except Exception as e:
    print(e)

// Request body
const body = {
    "task_id": "task_id"
};

fetch('https://gateway.appypie.com/kling-ai-polling/v1/getVirtualTryOnStatus', {
        method: 'POST',
        body: JSON.stringify(body),
        // Request headers
        headers: {
            'Content-Type': 'application/json',
            'Cache-Control': 'no-cache',}
    })
    .then(response => {
        console.log(response.status);
        console.log(response.text());
    })
    .catch(err => console.error(err));

curl -v -X POST "https://gateway.appypie.com/kling-ai-polling/v1/getVirtualTryOnStatus" -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data-raw "{
    \"task_id\": \"task_id\"
}"

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.util.HashMap;
import java.util.Map;
import java.io.UnsupportedEncodingException;
import java.io.DataInputStream;
import java.io.InputStream;
import java.io.FileInputStream;

public class HelloWorld {

  public static void main(String[] args) {
    try {
        String urlString = "https://gateway.appypie.com/kling-ai-polling/v1/getVirtualTryOnStatus";
        URL url = new URL(urlString);
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();

        //Request headers
    connection.setRequestProperty("Content-Type", "application/json");
    
    connection.setRequestProperty("Cache-Control", "no-cache");
    
        connection.setRequestMethod("POST");

        // Request body
        connection.setDoOutput(true);
        connection
            .getOutputStream()
            .write(
             "{ \"task_id\": \"task_id\" }".getBytes()
             );
    
        int status = connection.getResponseCode();
        System.out.println(status);

        BufferedReader in = new BufferedReader(
            new InputStreamReader(connection.getInputStream())
        );
        String inputLine;
        StringBuffer content = new StringBuffer();
        while ((inputLine = in.readLine()) != null) {
            content.append(inputLine);
        }
        in.close();
        System.out.println(content);

        connection.disconnect();
    } catch (Exception ex) {
      System.out.print("exception:" + ex.getMessage());
    }
  }
}

$url = "https://gateway.appypie.com/kling-ai-polling/v1/getVirtualTryOnStatus";
$curl = curl_init($url);

curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

# Request headers
$headers = array(
    'Content-Type: application/json',
    'Cache-Control: no-cache',);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

# Request body
$request_body = '{
    "task_id": ""
}';
curl_setopt($curl, CURLOPT_POSTFIELDS, $request_body);

$resp = curl_exec($curl);
curl_close($curl);
var_dump($resp);

Response for Polling

Upon successful polling, the API returns a response indicating the video generation status and the URL of the generated video if it is complete.

Example Success Response

JSON

{
    "code": 0,
    "message": "SUCCEED",
    "request_id": "Cji7DWc7DlsAAAAAAALyfg",
    "data": {
        "task_id": "ChBRS2c7DlgAAAAAAAXXXX",
        "task_status": "succeed",
        "task_status_msg": "",
        "task_info": {},
        "task_result": {
            "images": [{
                "index": 0,
                "url": "https://cdn.klingai.com/bs2/upload-kling-api/7128237050/virtualTryOn/ChBRS2c7DlgAAAAAAAIzCw-0.png"
            }]
        },
        "created_at": 1731928289693,
        "updated_at": 1731928309425
    }
}

Response Handling

Kolors Virtual Try-On API provides specific HTTP status codes and detailed response bodies to indicate the outcome of a request. Developers should implement robust error handling in their applications to process these responses effectively and ensure a seamless user experience.

Common Status Codes and Responses

Status Code	Description	Response Body
200	Success - The request was successfully processed, and the image generation is in progress or completed.	{ "msg": "Image Getting Created", ... }
400	Bad Request - The request contains invalid parameters or missing fields.	{ "error": "Invalid request parameters" }
401	Unauthorized - The provided subscription key is missing or invalid.	{ "error": "Invalid or missing authentication" }
403	Forbidden - The subscription does not have access to this API or action.	{ "error": "Access denied for this operation" }
404	Not Found - The requested resource or endpoint could not be found.	{ "error": "Endpoint not found" }
429	Too Many Requests - The request rate limit has been exceeded.	{ "error": "Rate limit exceeded, please retry later" }
500	Internal Server Error - An unexpected error occurred on the server.	{ "error": "An unexpected error occurred, please try again later" }

Example Error Response

{
        "task_status": "failed",
        "task_status_msg": "task not found"
}

Conclusion

This documentation outlines all the key details needed to effectively utilize Kolors Virtual Try-On API. Ensure that you replace YOUR_SUBSCRIPTION_KEY with the actual key provided upon subscribing to the service.

Get API Key

Text-to-Image

Text to Video

Image to Video

Virtual Try-on

Text Generation

Virtual Try-On API Documentation

Authentication:

Request Headers:

Endpoint

Request Body Parameters

Example Request Body

Request Code

Input

Response

Next Step: Polling Results

Retrieving Image Status and URL

Polling Endpoint

Request Headers:

Request Body Parameters

Request Body

Example Request Body

Request Code

Input

Response for Polling

Example Success Response

Response Handling

Common Status Codes and Responses

Example Error Response

Conclusion