API Documentation
Integrate AI-powered virtual try-on technology into your applications with our powerful RESTful API.
Sign Up for API AccessGetting 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
- Create an account and get an API key on the settings page
- Send a POST request to
/generatewith your chosen style - Upload images as base64: person + clothing (Virtual Try-On) or product photo (Product Catalog)
- Get
order_idand poll/orders/{id}until completion (~1-3 minutes) - 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.
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
/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") |
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.
/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
/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:
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 DevelopmentPython
Coming Soon
In DevelopmentPHP
Coming Soon
In DevelopmentNeed 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!