Name: IDM-VTON – AI Virtual Clothes Try-On | $0.07/call | API.market
Brand: magicapi
SKU: api-magicapi-virtual-clothing-try-on-api
Availability: InStock
Rating: 5.00 (1 reviews)
Author: API Market

Shashank Agarwal

# 👗 Realistic Clothing Try-On API (IDM-VTON) – AI-Powered Fitting

## Overview
The Realistic Clothing Try-On API (IDM-VTON) allows you to digitally fit garments on images of people with striking realism. Using cutting-edge AI, this API seamlessly merges the garment image with the model (person) image to create a natural-looking try-on result. This is ideal for virtual fitting rooms, e-commerce product previews, and any application involving apparel visualization. Note that this service is provided for non-commercial use only.

## Features
- High-fidelity image compositing to virtually showcase clothing on human models
- Supports various garment categories, including upper_body, lower_body, and dresses
- Options to crop and mask images for better results​
- Adjustable steps and random seed for fine-tuning outputs
- Asynchronous prediction handling for efficient scaling

## Use Cases
1. E-Commerce Virtual Fitting: Allow shoppers to see how a piece of clothing looks on a real model or themselves before purchase.  
2. Fashion Design Mockups: Quickly prototype how new designs appear on different body types.  
3. Personal Wardrobe Styling: Experiment with outfits virtually without physically trying them on.  
4. Social Media and Digital Campaigns: Create realistic outfit visuals for marketing content.  
5. Costume or Cosplay Previews: Visualize costumes on yourself or your character images for themed events.

## Visual Examples

Below are some example images demonstrating input and output from the API:

### Example Garment Image
![Garment image used as input](https://replicate.delivery/pbxt/KgwTlZyFx5aUU3gc5gMiKuD5nNPTgliMlLUWx160G4z99YjO/sweater.webp)

### Example Human Image
![Human model image used as input](https://replicate.delivery/pbxt/KgwTlhCMvDagRrcVzZJbuozNJ8esPqiNAIJS3eMgHrYuHmW4/KakaoTalk_Photo_2024-04-04-21-44-45.png)

### Example Mask Image (Optional)
![Optional mask image for improved performance](https://example.com/image.jpg)

### Example Output (Result)
![AI-generated output image showing the garment realistically fitted on the human model](https://replicate.delivery/pbxt/Tfs5JETdzlURKyKeUOltKwch7udHf8e2xmNsftwid7ca2E6UC/output.jpg)

By providing a garment image and a human model image (optionally with a mask), the API produces a near photo-realistic rendition of the garment worn by the model.

## Pricing
• 1 API unit equals 1 image processed.  
• Checking prediction status with GET /api/v1/magicapi/virtual-clothing-try-on-api/predictions/{id} does not consume any additional units.  
• Various pricing tiers are offered based on usage volume (contact us for details).

## API Documentation

### Base URL
All requests should be sent to the base URL below:  
```
https://prod.api.market/api/v1/magicapi/virtual-clothing-try-on-api
```

### Authentication
Include your API key in every request header:
```
x-magicapi-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This API uses asynchronous prediction. The typical flow is:
1. Submit a POST request to create a prediction.  
2. Receive a prediction ID from the response.  
3. Poll the GET endpoint with the prediction ID to check the status.  
4. Continue polling until the prediction is complete or failed.

Polling interval recommendation: 1 second.  
Maximum polling timeout: 600 seconds (10 minutes).  

### Endpoints

#### POST /api/v1/magicapi/virtual-clothing-try-on-api/predictions
Create a new prediction (i.e., start the try-on process).

• Method: POST  
• Authentication: Required  
• Request Body (JSON):
  
```json
{
  "version": "0513734a452173b8173e907e3a59d19a36266e55b48528559432bd21c7d7e985",
  "input": {
    "category": "upper_body",
    "crop": false,
    "force_dc": false,
    "garm_img": "https://replicate.delivery/pbxt/KgwTlZyFx5aUU3gc5gMiKuD5nNPTgliMlLUWx160G4z99YjO/sweater.webp",
    "garment_des": "cute pink top",
    "human_img": "https://replicate.delivery/pbxt/KgwTlhCMvDagRrcVzZJbuozNJ8esPqiNAIJS3eMgHrYuHmW4/KakaoTalk_Photo_2024-04-04-21-44-45.png",
    "mask_img": "",
    "mask_only": false,
    "seed": 42,
    "steps": 30
  }
}
```

• Sample cURL request:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/virtual-clothing-try-on-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "0513734a452173b8173e907e3a59d19a36266e55b48528559432bd21c7d7e985",
    "input": {
      "garm_img": "https://replicate.delivery/pbxt/KgwTlZyFx5aUU3gc5gMiKuD5nNPTgliMlLUWx160G4z99YjO/sweater.webp",
      "garment_des": "cute pink top",
      "human_img": "https://replicate.delivery/pbxt/KgwTlhCMvDagRrcVzZJbuozNJ8esPqiNAIJS3eMgHrYuHmW4/KakaoTalk_Photo_2024-04-04-21-44-45.png",
      "category": "upper_body",
      "crop": false,
      "force_dc": false,
      "mask_img": "",
      "mask_only": false,
      "seed": 42,
      "steps": 30
    }
  }'
```

• Response (JSON):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "0513734a452173b8173e907e3a59d19a36266e55b48528559432bd21c7d7e985",
  "status": "starting",
  "created_at": "2025-04-20T10:51:02.568Z"
}
```
When this request succeeds, note the "id" field. You will use the ID to poll for status and retrieve the final output.

---

#### GET /api/v1/magicapi/virtual-clothing-try-on-api/predictions/{id}
Retrieve the status and (when completed) the output of a prediction job.

• Method: GET  
• Authentication: Required  
• Path Parameter:  
  - {id}: The ID returned from the POST /predictions request.

• Sample cURL request:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/virtual-clothing-try-on-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

• Response (JSON) when succeeded:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://replicate.delivery/pbxt/Tfs5JETdzlURKyKeUOltKwch7udHf8e2xmNsftwid7ca2E6UC/output.jpg",
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```

• Example fields:  
  - status: Can be "starting", "processing", "succeeded", "failed", or "canceled"  
  - output: URL to the final image if status is "succeeded"  
  - error: Present only if status is "failed"

## Status Codes
- 200 OK: Request completed successfully.  
- 201 Created: A new resource (e.g., prediction) was successfully created.  
- 400 Bad Request: Invalid input or request. Double-check your JSON body/parameters.  
- 401 Unauthorized: Invalid or missing API key.  
- 403 Forbidden: API key is valid but lacks permission for the requested resource.  
- 404 Not Found: The specified resource doesn’t exist (e.g., an invalid prediction ID).  
- 429 Too Many Requests: You have exceeded your plan’s rate or usage limits.  
- 500 Internal Server Error: An error occurred on the server side. Try again later or contact support.  
- 503 Service Unavailable: Service is temporarily down or undergoing maintenance.

## Rate Limits
This API may throttle requests based on usage tier. If you hit the rate limit (429 Too Many Requests), wait briefly before retrying. Consider upgrading to a higher usage plan if you consistently encounter rate-limit issues.

## Error Handling
When an error occurs, the API returns a JSON response with details. Sample format:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'garm_img' is required",
    "status": 400
  }
}
```

Best practices:
- Check the status code to determine specific error handling steps.  
- Look at the "error" object to get a human-readable error message.  
- Implement retries for transient errors like 429 or 503.  
- For 4xx errors, correct the request before retrying.  

## Implementation Guide

Below are high-level code examples demonstrating how to create a prediction, poll for results, and handle errors. Adjust these to suit your environment.

### Example Code in JavaScript

```javascript
// JavaScript example with proper polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/virtual-clothing-try-on-api";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-magicapi-key": apiKey
      },
      body: JSON.stringify({
        version: "0513734a452173b8173e907e3a59d19a36266e55b48528559432bd21c7d7e985",
        input: inputData
      })
    });
    
    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }
    
    const prediction = await response.json();
    const predictionId = prediction.id;
    
    // Step 2: Poll for results with timeout
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second
  
  const startTime = Date.now();

  while ((Date.now() - startTime) < MAX_TIMEOUT) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: {
        "x-magicapi-key": apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed") {
      throw new Error(`Prediction failed: ${prediction.error || "Unknown error"}`);
    }
    
    // Wait before next poll
    await delay(POLL_INTERVAL);
  }
  
  throw new Error("Prediction timed out after 10 minutes");
}

// Usage example
(async () => {
  const inputData = {
    garm_img: "https://replicate.delivery/pbxt/KgwTlZyFx5aUU3gc5gMiKuD5nNPTgliMlLUWx160G4z99YjO/sweater.webp",
    human_img: "https://replicate.delivery/pbxt/KgwTlhCMvDagRrcVzZJbuozNJ8esPqiNAIJS3eMgHrYuHmW4/KakaoTalk_Photo_2024-04-04-21-44-45.png",
    garment_des: "cute pink top"
  };
  
  try {
    const outputUrl = await createAndWaitForPrediction(inputData);
    console.log("Output Image URL:", outputUrl);
  } catch (err) {
    console.error(err);
  }
})();
```

### Example Code in Python

```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/virtual-clothing-try-on-api"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }
    
    payload = {
        "version": "0513734a452173b8173e907e3a59d19a36266e55b48528559432bd21c7d7e985",
        "input": input_data
    }
    
    response = requests.post(f"{BASE_URL}/predictions", json=payload, headers=headers)
    
    # Note: API might return 201, but we treat 200 and 201 the same in this example
    if response.status_code not in (200, 201):
        raise Exception(f"API error: {response.status_code} {response.text}")
    
    prediction = response.json()
    prediction_id = prediction["id"]
    
    # Step 2: Poll for results with timeout
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second
    
    headers = {"x-magicapi-key": API_KEY}
    start_time = time.time()
    
    while time.time() - start_time < MAX_TIMEOUT:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)
        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")
        
        prediction = response.json()
        
        if prediction["status"] == "succeeded":
            return prediction["output"]
        elif prediction["status"] == "failed":
            raise Exception(f"Prediction failed: {prediction.get('error', 'Unknown error')}")
        
        time.sleep(POLL_INTERVAL)
    
    raise Exception("Prediction timed out after 10 minutes")

if __name__ == "__main__":
    try:
        input_data = {
            "garm_img": "https://replicate.delivery/pbxt/KgwTlZyFx5aUU3gc5gMiKuD5nNPTgliMlLUWx160G4z99YjO/sweater.webp",
            "human_img": "https://replicate.delivery/pbxt/KgwTlhCMvDagRrcVzZJbuozNJ8esPqiNAIJS3eMgHrYuHmW4/KakaoTalk_Photo_2024-04-04-21-44-45.png",
            "garment_des": "cute pink top"
        }
        output_url = create_and_wait_for_prediction(input_data)
        print("Output Image URL:", output_url)
    except Exception as e:
        print("Error:", e)
```

### Example cURL Workflow

```bash
 1) Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/virtual-clothing-try-on-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "0513734a452173b8173e907e3a59d19a36266e55b48528559432bd21c7d7e985",
    "input": {
      "garm_img": "https://replicate.delivery/pbxt/KgwTlZyFx5aUU3gc5gMiKuD5nNPTgliMlLUWx160G4z99YjO/sweater.webp",
      "human_img": "https://replicate.delivery/pbxt/KgwTlhCMvDagRrcVzZJbuozNJ8esPqiNAIJS3eMgHrYuHmW4/KakaoTalk_Photo_2024-04-04-21-44-45.png",
      "garment_des": "cute pink top"
    }
  }'

Sample response:
 {
   "id": "abcd1234",
   "status": "starting"
 }

 2) Poll the prediction status (until status is "succeeded")
curl -X GET "https://prod.api.market/api/v1/magicapi/virtual-clothing-try-on-api/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- Provide a mask image if available, as it can improve processing speed and accuracy.  
- Use an appropriate cropping mode if the human image ratio is different from 3:4.  
- If you only need the mask (i.e., silhouette of the garment), enable mask_only.  

## FAQ
1. **What image formats are supported?**  
   Most common formats (PNG, JPG, WEBP) are accepted. Provide standard URLs pointing to your images.  

2. **Why is my image cropping incorrectly?**  
   If the input human image has a low aspect ratio or is not 3:4, set "crop": true to improve alignment.

3. **How long does it take to complete a prediction?**  
   Processing typically finishes within seconds, but it can take up to a few minutes depending on server load and the complexity of the image.

4. **Can I modify the appearance of the garment?**  
   Beyond the basic parameters, modifications are minimal. For advanced editing, consider additional AI-powered image manipulation tools.

5. **Is there a limit to how many images I can process?**  
   Yes, based on your plan. If you need higher volume, contact us to discuss upgraded tiers.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello[at]api.market.

Digitally fit clothes onto any person's photo with AI. Supports dresses, tops, and pants for realistic e-commerce previews. Try it free on API.market.

IDM-VTON – AI Virtual Clothes Try-On | $0.07/call | API.market