Language
🇺🇸 EN
Sign in Get Started

API Documentation

Integrate AI-powered virtual try-on technology into your applications with our powerful RESTful API.

Sign Up for API Access

Getting Started

FtmvAI.com API allows you to programmatically generate virtual try-on images using AI. Our API is RESTful and returns JSON responses with asynchronous processing.

Base URL

https://ftmvai.com/api/v1

How It Works

Virtual Try-On: Upload person photo + clothing item → AI generates realistic try-on → Download result image (1 credit)

Product Catalog: Upload product photo → AI generates 6 or 12 professional catalog images → Download all variations (24 or 36 credits)

Perfect for e-commerce, fashion apps, product photography, or any application where users want to visualize products before buying.

Quick Start

  1. Create an account and get an API key on the settings page
  2. Send a POST request to /generate with your chosen style
  3. Upload images as base64: person + clothing (Virtual Try-On) or product photo (Product Catalog)
  4. Get order_id and poll /orders/{id} until completion (~1-3 minutes)
  5. Download ready AI-generated results from the obtained URLs

Real AI Generation

API uses advanced machine learning algorithms to create realistic virtual try-on images and professional product catalog photos. Processing takes 1-3 minutes to ensure high-quality results.

Authentication

All API requests require authentication using your API key. Include the API key in the request headers.

Headers
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
⚠️

Keep API Key Secure

Never expose your API key in client code. Always make API calls from your server.

💡

Example API Key

Your API key looks something like this:

your_api_key_here_64_characters_long_example_1234567890abcdef

API Endpoints

Three Simple Endpoints

POST /generate - Create a virtual try-on (upload images, get order ID)
GET /orders/{id} - Check status and get results
GET /account - Check your credits and usage
POST /generate

Create AI-generated images. Supports two styles: Virtual Try-On (person + clothing) and Product Catalog (professional product photos). Returns order_id for tracking status.

Request Body (Virtual Try-On)

{
  "style": "virtual_tryon",
  "person_image": "base64_encoded_person_photo",
  "clothing_image": "base64_encoded_clothing_item",
  "options": {
    "quality": "high",
    "format": "jpg"
  }
}

Request Body (Product Catalog)

{
  "style": "product_catalog",
  "product_image": "base64_encoded_product_photo",
  "quantity": 6,  // 6 or 12
  "options": {
    "quality": "high",
    "format": "jpg"
  }
}

Parameters

Parameter Type Required Description
style string No "virtual_tryon" or "product_catalog" (default: "virtual_tryon")
person_image string Yes* Base64 encoded person photo (required for virtual_tryon)
clothing_image string Yes* Base64 encoded clothing item (required for virtual_tryon)
product_image string Yes* Base64 encoded product photo (required for product_catalog)
quantity number Yes* 6 (24 credits) or 12 (36 credits) - required for product_catalog
options.quality string No Output quality: "standard" or "high" (default: "high")
options.format string No Output format: "jpg" or "png" (default: "jpg")
* Required parameters depend on the chosen style

Response (HTTP 202 Accepted)

{
  "success": true,
  "order_id": 47,
  "status": "pending",
  "credits_used": 1,
  "message": "Order created successfully. Use the orders endpoint to check status.",
  "estimated_time": "45-60 seconds",
  "created_at": "2025-06-14T15:00:43+00:00"
}
ℹ️

Asynchronous Processing

API returns HTTP 202 (Accepted) and immediately provides order_id. Use endpoint /orders/{order_id} to check status and get results.

GET /orders/{order_id}

Get status and results of a specific order. Use for tracking progress of generation.

Response (in progress)

{
  "success": true,
  "order": {
    "id": 47,
    "status": "in_progress",
    "credits_used": 1,
    "progress": 65,
    "created_at": "2025-06-14T15:00:43+00:00",
    "estimated_completion": "2025-06-14T15:02:00+00:00"
  }
}

Response (completed - Virtual Try-On)

{
  "success": true,
  "order": {
    "id": 47,
    "status": "completed",
    "credits_used": 1,
    "results": {
      "person_url": "https://ftmvai.com/uploads/person_47_xxx.jpg",
      "clothing_url": "https://ftmvai.com/uploads/clothing_47_xxx.jpg",
      "result_url": "https://ftmvai.com/uploads/result_47_xxx.jpg"
    },
    "created_at": "2025-06-14T15:00:43+00:00",
    "completed_at": "2025-06-14T15:01:52+00:00",
    "processing_time": 69
  }
}

Response (completed - Product Catalog)

{
  "success": true,
  "order": {
    "id": 48,
    "status": "completed",
    "credits_used": 24,
    "results": {
      "product_url": "https://ftmvai.com/uploads/product_48_xxx.jpg",
      "catalog_images": [
        "https://ftmvai.com/uploads/catalog_48_1.jpg",
        "https://ftmvai.com/uploads/catalog_48_2.jpg",
        "https://ftmvai.com/uploads/catalog_48_3.jpg",
        "https://ftmvai.com/uploads/catalog_48_4.jpg",
        "https://ftmvai.com/uploads/catalog_48_5.jpg",
        "https://ftmvai.com/uploads/catalog_48_6.jpg"
      ],
      "quantity": 6,
      "product_description": "Professional product photography"
    },
    "created_at": "2025-06-14T15:00:43+00:00",
    "completed_at": "2025-06-14T15:03:15+00:00",
    "processing_time": 152
  }
}
💡

Order Statuses

  • pending - order created, waiting for processing
  • in_progress - AI generating try-on
  • completed - result ready, URLs available
  • failed - processing error
GET /account

Get information about your account and credit balance.

Response

{
  "success": true,
  "account": {
    "user_id": 5,
    "credits_remaining": 87,
    "api_calls_today": 3,
    "api_calls_total": 15,
    "plan": "free"
  },
  "rate_limit": {
    "limit": 100,
    "remaining": 97,
    "reset": 1749900600
  }
}

Error Handling

API uses standard HTTP response codes to indicate success or failure. All errors include JSON body with details.

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits for this operation",
    "details": {
      "credits_required": 1,
      "credits_available": 0
    }
  }
}

HTTP Status Codes

Status Code Value
200 Success
202 Accepted - order created, processing asynchronously
400 Bad Request - incorrect parameters
401 Unauthorized - incorrect API key
402 Payment Required - insufficient credits
429 Too Many Requests - exceeded limit
500 Internal Server Error

Rate Limits

To ensure fair usage and optimal performance, API has limits based on your account type.

Free Plan

  • • 10 requests per hour
  • • 50 requests per day
  • • 1 simultaneous request

Paid Plans

  • • 100 requests per hour
  • • 1000 requests per day
  • • 5 simultaneous requests

Rate Limit Headers

Each API response includes rate limit information in headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1749900600

Code Examples

JavaScript (Node.js)

const fs = require('fs');
const fetch = require('node-fetch');

async function generateVirtualTryOn(personImagePath, clothingImagePath) {
  try {
    // Read and encode images
    const personBuffer = fs.readFileSync(personImagePath);
    const clothingBuffer = fs.readFileSync(clothingImagePath);
    const base64PersonImage = personBuffer.toString('base64');
    const base64ClothingImage = clothingBuffer.toString('base64');
    
    // Create order
    const response = await fetch('https://ftmvai.com/api/v1/generate', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        person_image: base64PersonImage,
        clothing_image: base64ClothingImage,
        options: {
          quality: 'high',
          format: 'jpg'
        }
      })
    });
    
    const result = await response.json();
    
    if (!result.success) {
      throw new Error(result.error.message);
    }
    
    console.log(`Order created: ${result.order_id}`);
    console.log('Waiting for completion...');
    
    // Poll for completion
    const orderId = result.order_id;
    let completed = false;
    
    while (!completed) {
      await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
      
      const statusResponse = await fetch(`https://ftmvai.com/api/v1/orders/${orderId}`, {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      });
      
      const statusResult = await statusResponse.json();
      
      if (statusResult.success) {
        const order = statusResult.order;
        console.log(`Status: ${order.status}`);
        
        if (order.status === 'completed') {
          console.log('Virtual try-on generated successfully!');
          console.log('Person:', order.results.person_url);
          console.log('Clothing:', order.results.clothing_url);
          console.log('Result:', order.results.result_url);
          completed = true;
          return order;
        } else if (order.status === 'failed') {
          throw new Error('Generation failed');
        }
      }
    }
  } catch (error) {
    console.error('Error:', error.message);
    throw error;
  }
}

// Usage
generateVirtualTryOn('./path/to/person.jpg', './path/to/clothing.jpg')
  .then(result => console.log('Done!', result))
  .catch(error => console.error('Failed:', error));

Python

import requests
import base64
import time

def generate_virtual_tryon(person_image_path, clothing_image_path, api_key='YOUR_API_KEY'):
    try:
        # Read and encode images
        with open(person_image_path, 'rb') as person_file:
            base64_person = base64.b64encode(person_file.read()).decode('utf-8')
        with open(clothing_image_path, 'rb') as clothing_file:
            base64_clothing = base64.b64encode(clothing_file.read()).decode('utf-8')
        
        # Create order
        url = 'https://ftmvai.com/api/v1/generate'
        headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }
        
        data = {
            'person_image': base64_person,
            'clothing_image': base64_clothing,
            'options': {
                'quality': 'high',
                'format': 'jpg'
            }
        }
        
        response = requests.post(url, headers=headers, json=data)
        result = response.json()
        
        if not result['success']:
            raise Exception(result['error']['message'])
        
        order_id = result['order_id']
        print(f"Order created: {order_id}")
        print("Waiting for completion...")
        
        # Poll for completion
        while True:
            time.sleep(5)  # Wait 5 seconds
            
            status_url = f'https://ftmvai.com/api/v1/orders/{order_id}'
            status_response = requests.get(status_url, headers=headers)
            status_result = status_response.json()
            
            if status_result['success']:
                order = status_result['order']
                print(f"Status: {order['status']}")
                
                if order['status'] == 'completed':
                    print("Virtual try-on generated successfully!")
                    print(f"Person: {order['results']['person_url']}")
                    print(f"Clothing: {order['results']['clothing_url']}")
                    print(f"Result: {order['results']['result_url']}")
                    return order
                elif order['status'] == 'failed':
                    raise Exception("Generation failed")
            else:
                raise Exception("Failed to check status")
                
    except Exception as e:
        print(f"Error: {e}")
        raise

# Usage
if __name__ == "__main__":
    try:
        # Replace with paths to your actual image files
        result = generate_virtual_tryon('path/to/person.jpg', 'path/to/clothing.jpg')
        print("Done!", result)
    except Exception as e:
        print(f"Failed: {e}")

PHP

Error: Person image file not found: path/to/person.jpg
Failed: Person image file not found: path/to/person.jpg

Official SDKs

We're working on official SDKs for popular programming languages to make integration even easier.

📦

JavaScript/TypeScript

Coming Soon

In Development
🐍

Python

Coming Soon

In Development
🐘

PHP

Coming Soon

In Development

Need Help?

Have questions about our API? Our support team is ready to help you successfully integrate our service.

🚀

Ready to Start?

Create an account, get an API key, and start generating virtual try-on images today!