API Documentation

Introduction

Welcome to the Try-on API documentation.

Our API enables you to implement virtual try-on for apparel by combining person and garment photos, as well as image-to-try-on operations for footwear (AR try-on). This documentation outlines the available endpoints and how to use them with your API key.

All API requests require authentication using your API key, which you can generate from the Dashboard after logging in.

OpenAPI Specification: For the complete API documentation in OpenAPI 3.1 format, view our OpenAPI specification. You can use this with tools like Swagger UI or import it into your API client.

Authentication

Include your API key in all requests using the following HTTP header:

Authorization: Bearer <YOUR_API_KEY>

👗 Apparel Try-on

Virtual clothing try-on using person and garment photos

POST `/api/v1/tryon`

Submits a new virtual try-on job. Cost: 1 credit

Request

Content-Type: multipart/form-data

Request Body Parameters

Field Name	Type	Required	Description
person_images	File	Yes	One person image file. Public URLs are not currently supported.
garment_images	File	Yes	One garment image file. Public URLs are not currently supported.
fast_mode	String	No	Set to "true" or "1" to enable fast mode. Skips result verification and returns the first generated result instantly for faster processing.

Note: Currently only supports one image for person and garment each.

Response

202 Accepted

{
  "jobId": "b16367b3-61a4-40aa-a713-f91889c3dae9",
  "statusUrl": "/api/v1/tryon/status/b16367b3-61a4-40aa-a713-f91889c3dae9"
}

Use the statusUrl to poll for the job result.

Error Responses

400 Bad Request - Missing files/URLs or invalid format.
401 Unauthorized - Invalid or missing API key.
402 Payment Required - Insufficient credits.
429 Too Many Requests - Rate limiting.
500 Internal Server Error - Unexpected server issues.

This endpoint initiates an asynchronous job. The response includes a job ID that you can use to check the status.

GET `/api/v1/tryon/status/{jobId}`

Retrieves the status and result of a try-on job.

Request

Path Parameter: jobId (The ID returned by the POST /api/v1/tryon call)

Authentication: API Key (must be the same key used to create the job or belong to the same user)

Response

200 OK

{
  "jobId": "11111111-1111-1111-1111-111111111111",
  "status": "processing | completed | failed",
  "imageUrl": "", // Present on 'completed'
  "imageBase64": "base64_string_data...", // Optional, present on 'completed'
  "message": "Job is still processing.", // Present on 'processing'
  "result": {} // Detailed information from the try-on service or error details
  "error": "Descriptive error message", // Top-level error, present on 'failed'
  "errorCode": "ERROR_CODE", // Top-level error code, present on 'failed'
  "createdAt": "iso_timestamp",
  "updatedAt": "iso_timestamp"
}

Notes:

imageUrl: Present when status is completed and the result is stored as an object. This can be a temporary signed URL (e.g., valid for 1 hour) or a permanent public URL if configured.
imageBase64: Present when status is completed if the image is returned directly as base64 data. This might occur as a fallback if URL generation is not possible or as a primary method depending on service configuration.
message: Present when status is processing, providing a human-readable update.
result: A nested object. For completed jobs, it may contain metadata about the generation (like objectKey). For failed jobs, it will contain detailed error information, including a provider-specific error message, errorCode, and potentially the internal step at which the failure occurred.
provider: Indicates which backend service generated the result.
Top-level error and errorCode: Present when status is failed, often mirroring details found within the result object.

Possible status values:

processing - The job is still being processed by the queue or the try-on service. (Includes internal states: queued, processing_from_queue)
completed - The job has completed successfully. The result image can be accessed via imageUrl or imageBase64.
failed - The job has failed during processing. Check error, errorCode, and the nested result object for details. (Includes internal states: invalid_input, error)

Possible errorCode values (when status is 'failed'):

INVALID_PERSON_IMAGE - The person image is invalid, unsuitable, or could not be processed.
INVALID_GARMENT_IMAGE - The garment image is invalid, unsuitable, or could not be processed.
VALIDATION_FAILED - A general validation check failed for the input images or parameters.
GENERATION_FAILED - The core try-on image generation process failed.
STORAGE_FAILED - An error occurred while attempting to save input or output images.
R2_FETCH_FAILED - The system failed to retrieve necessary image data from internal storage (R2).
RESULT_UNAVAILABLE - The job was marked as completed, but the final image URL or data could not be retrieved or provided.
QUEUE_INVALID_INPUT_DATA - The job message received from the processing queue had malformed or missing data.
CONSUMER_CONFIG_ERROR - The backend processing service encountered a configuration problem (e.g., missing API keys for AI models).
INVALID_SERVICE_PROVIDER - The configured try-on service provider is not recognized or supported.
QUEUE_PROCESSING_FAILED - A generic error occurred during the processing of the job from the queue.
SERVICE_SPECIFIC_ERROR - An error specific to the underlying AI service occurred (details often in result.error).
INTERNAL_ERROR - An unexpected internal server error occurred.

Error Responses

401 Unauthorized - Invalid or missing API key.
403 Forbidden - API key is valid, but does not have permission to access this job (key owner differs from job owner).
404 Not Found - Job ID does not exist.

You should poll this endpoint at regular intervals (e.g., every 2-5 seconds) until the job status is no longer processing.

👟 Footwear Try-on

Complete pipeline for image-to-3D footwear generation and AR try-on

POST `/api/v1/image-to-tryon`

Complete pipeline: generates 3D model from shoe image and uploads to WEARFITS for AR try-on. Cost: 5 credits (one-time)

⚠️ Image Requirements (AI Validated)

The API uses AI vision to validate shoe images. Your image must show:

Single shoe only (not a pair, not multiple items)
No foot inside the shoe
Clear side or angled view preferred
Good lighting and clarity
Complete shoe visible (not cropped)

❌ Non-shoe images (clothing, accessories, etc.) will be rejected to prevent wasting credits.

Request

Content-Type: multipart/form-data
Headers: X-WEARFITS-API-Key: your-wearfits-key (or store in user settings)

Request Body Parameters

Field Name	Type	Required	Description
image	File	Yes	Shoe image file (512px-6000px per side, max 20MB)
face_limit	Number	No	Triangle count limit (1000-100000, default: 20000)

Pipeline Process

Validates and generates 3D model from image (1-3 minutes)
Uploads GLB model to WearFits automatically (10-30 seconds)
Processes model for AR compatibility (30-90 seconds)
Returns ready-to-use AR viewer URL

⏱️ Total time: Typically 2-5 minutes for complete pipeline

Response

200 OK

{
  "success": true,
  "jobId": "pipeline-12345-67890",
  "statusUrl": "/api/v1/image-to-tryon/status/pipeline-12345-67890",
  "message": "Image-to-tryon pipeline started. The process will automatically generate a 3D model and upload it to WearFits for AR try-on."
}

GET `/api/v1/image-to-tryon/status/{jobId}`

Check the status of an image-to-tryon pipeline job. Poll every 10 seconds for optimal balance.

Response

200 OK

{
  "jobId": "pipeline-12345-67890",
  "status": "processing",
  "pipelineStage": "3d-generation",
  "progress": 45,
  "subProgress": {
    "model3d": 65
  },
  "message": "Generating 3D model... 65%"
}

// With WEARFITS sub-progress when available:
{
  "jobId": "pipeline-12345-67890",
  "status": "processing",
  "pipelineStage": "wearfits-processing",
  "progress": 90,
  "subProgress": {
    "wearfits": 45
  },
  "message": "Processing for AR try-on... 45%"
}

// When completed:
{
  "jobId": "pipeline-12345-67890",
  "status": "completed",
  "pipelineStage": "completed",
  "progress": 100,
  "tryonViewerUrl": "https://dev.wearfits.com/tryon/dev?object=xxx",
  "wearfitsModelId": "model-id",
  "wearfitsColorId": "color-id",
  "result": {
    "modelUrl": "https://...",
    "pbrModelUrl": "https://...",
    "renderedImageUrl": "https://..."
  },
  "success": true,
  "message": "Pipeline completed! Your shoe is ready for AR try-on."
}

Progress Tracking

progress: Overall pipeline progress (0-100%)
subProgress.model3d: 3D model generation progress (0-100%) when available
subProgress.wearfits: WEARFITS processing progress (0-100%) when available

Pipeline Stages

image-validation: Validating uploaded image (0-5%)
queued: Job queued for processing (10-15%)
3d-upload: Uploading images to 3D service (15-20%)
3d-generation: Generating 3D model from image (20-75%)
3d-download: Downloading 3D model (75-80%)
wearfits-upload: Uploading model to WEARFITS (80-85%)
wearfits-processing: Processing model for AR try-on (85-97%)
wearfits-finalizing: Finalizing AR viewer (97-100%)
completed: Pipeline completed successfully (100%)

// Example using fetch API
async function generateTryOn(apiKey, personImageUrl, garmentImageUrl, fastMode = false) {
  // Create FormData
  const formData = new FormData();
  formData.append('person_images', personImageUrl);
  formData.append('garment_images', garmentImageUrl);
  if (fastMode) {
    formData.append('fast_mode', 'true');
  }
  
  // Submit job
  const response = await fetch('https://your-domain.com/api/v1/tryon', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`
    },
    body: formData
  });
  
  if (!response.ok) {
    throw new Error(`HTTP error ${response.status}`);
  }
  
  const { jobId, statusUrl } = await response.json();
  
  // Poll for result
  let resultUrl;
  let jobStatus = 'processing';
  
  while (jobStatus === 'processing') {
    await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2 seconds
    
    const statusResponse = await fetch(`https://your-domain.com${statusUrl}`, {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });
    
    if (!statusResponse.ok) {
      throw new Error(`Status check failed: ${statusResponse.status}`);
    }
    
    const statusData = await statusResponse.json();
    jobStatus = statusData.status;
    
    if (jobStatus === 'completed') {
      resultUrl = statusData.imageUrl;
      break;
    }
    
    if (jobStatus === 'failed' || jobStatus === 'invalid_input') {
      throw new Error(`Job failed: ${statusData.error} (${statusData.errorCode})`);
    }
  }
  
  return resultUrl;
}

import requests
import time

def generate_tryon(api_key, person_image_path, garment_image_path, fast_mode=False):
    # Prepare the request
    headers = {
        'Authorization': f'Bearer {api_key}'
    }
    
    files = {
        'person_images': open(person_image_path, 'rb'),
        'garment_images': open(garment_image_path, 'rb')
    }
    
    data = {}
    if fast_mode:
        data['fast_mode'] = 'true'
    
    # Submit job
    response = requests.post(
        'https://your-domain.com/api/v1/tryon',
        headers=headers,
        files=files,
        data=data
    )
    
    response.raise_for_status()
    data = response.json()
    job_id = data['jobId']
    status_url = data['statusUrl']
    
    # Poll for result
    job_status = 'processing'
    result_url = None
    
    while job_status == 'processing':
        time.sleep(2)  # Wait 2 seconds
        
        status_response = requests.get(
            f'https://your-domain.com{status_url}',
            headers=headers
        )
        
        status_response.raise_for_status()
        status_data = status_response.json()
        job_status = status_data['status']
        
        if job_status == 'completed':
            result_url = status_data['imageUrl']
            break
        
        if job_status in ['failed', 'invalid_input']:
            raise Exception(f"Job failed: {status_data.get('error')} ({status_data.get('errorCode')})")
    
    return result_url

# Submit a try-on job
curl -X POST \
  -H "Authorization: Bearer your_api_key_here" \
  -F "person_images=@/path/to/person.jpg" \
  -F "garment_images=@/path/to/garment.jpg" \
  https://your-domain.com/api/v1/tryon

# Submit a try-on job with fast mode enabled
curl -X POST \
  -H "Authorization: Bearer your_api_key_here" \
  -F "person_images=@/path/to/person.jpg" \
  -F "garment_images=@/path/to/garment.jpg" \
  -F "fast_mode=true" \
  https://your-domain.com/api/v1/tryon

# Response:
# {
#   "jobId": "b16367b3-61a4-40aa-a713-f91889c3dae9",
#   "statusUrl": "/api/v1/tryon/status/b16367b3-61a4-40aa-a713-f91889c3dae9"
# }

# Check job status
curl -X GET \
  -H "Authorization: Bearer your_api_key_here" \
  https://your-domain.com/api/v1/tryon/status/b16367b3-61a4-40aa-a713-f91889c3dae9

# Example response for completed job:
# {
#   "jobId": "b16367b3-61a4-40aa-a713-f91889c3dae9",
#   "status": "completed",
#   "imageUrl": "https://your-domain.com/image/b16367b3-61a4-40aa-a713-f91889c3dae9.jpg",
#   "provider": "service-id",
#   "createdAt": "2023-09-15T12:34:56Z",
#   "updatedAt": "2023-09-15T12:35:30Z"
# }

👟 Footwear API Examples

Complete image-to-3D AR try-on pipeline with progress tracking

// Example: Complete footwear AR try-on pipeline with progress tracking
async function generateFootwearTryOn(apiKey, shoeImageFile, wearfitsApiKey) {
  const API_URL = 'https://tryon-api.com';

  // Create FormData with shoe image
  const formData = new FormData();
  formData.append('image', shoeImageFile);

  // Submit job with WEARFITS API key
  console.log('📤 Submitting shoe image...');
  const response = await fetch(`${API_URL}/api/v1/image-to-tryon`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'X-WEARFITS-API-Key': wearfitsApiKey
    },
    body: formData
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Submission failed: ${error.error}`);
  }

  const { jobId, statusUrl } = await response.json();
  console.log('✅ Job submitted:', jobId);

  // Poll for completion with progress tracking
  let complete = false;
  let attempts = 0;
  const maxAttempts = 60; // 10 minutes max

  while (!complete && attempts < maxAttempts) {
    await new Promise(resolve => setTimeout(resolve, 10000)); // Poll every 10 seconds
    attempts++;

    const statusResponse = await fetch(`${API_URL}${statusUrl}`, {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    });

    if (!statusResponse.ok) {
      console.warn(`Status check failed: ${statusResponse.status}`);
      continue;
    }

    const status = await statusResponse.json();

    // Display progress
    console.log(`[${attempts * 10}s] ${status.pipelineStage} - ${status.progress}%`);
    if (status.subProgress?.model3d) {
      console.log(`  3D Generation: ${status.subProgress.model3d}%`);
    }
    if (status.subProgress?.wearfits) {
      console.log(`  WEARFITS Processing: ${status.subProgress.wearfits}%`);
    }

    if (status.status === 'completed') {
      complete = true;
      console.log('🎉 Pipeline completed!');
      console.log('AR Try-on URL:', status.tryonViewerUrl);
      console.log('WEARFITS Model ID:', status.wearfitsModelId);
      return {
        tryonUrl: status.tryonViewerUrl,
        modelId: status.wearfitsModelId,
        colorId: status.wearfitsColorId
      };
    } else if (status.status === 'failed') {
      throw new Error(`Pipeline failed: ${status.error}`);
    }
  }

  throw new Error('Pipeline timeout - check status URL later');
}

// Usage example
const apiKey = 'your_api_key_here';
const wearfitsKey = 'your_wearfits_key_here';
const shoeImage = document.getElementById('shoe-upload').files[0];

generateFootwearTryOn(apiKey, shoeImage, wearfitsKey)
  .then(result => console.log('AR Try-on ready:', result.tryonUrl))
  .catch(error => console.error('Error:', error));

import requests
import time

def generate_footwear_tryon(api_key, shoe_image_path, wearfits_api_key):
    """
    Complete footwear AR try-on pipeline with progress tracking

    Args:
        api_key: Your Try-on API key
        shoe_image_path: Path to shoe image file
        wearfits_api_key: Your WEARFITS API key

    Returns:
        dict: Contains tryonUrl, modelId, colorId
    """
    API_URL = 'https://tryon-api.com'

    # Submit job
    headers = {
        'Authorization': f'Bearer {api_key}',
        'X-WEARFITS-API-Key': wearfits_api_key
    }

    files = {'image': open(shoe_image_path, 'rb')}

    print('📤 Submitting shoe image...')
    response = requests.post(
        f'{API_URL}/api/v1/image-to-tryon',
        headers=headers,
        files=files
    )

    response.raise_for_status()
    data = response.json()
    job_id = data['jobId']
    status_url = data['statusUrl']

    print(f'✅ Job submitted: {job_id}')

    # Poll for completion with progress tracking
    complete = False
    attempts = 0
    max_attempts = 60  # 10 minutes max

    while not complete and attempts < max_attempts:
        time.sleep(10)  # Poll every 10 seconds
        attempts += 1

        status_response = requests.get(
            f'{API_URL}{status_url}',
            headers={'Authorization': f'Bearer {api_key}'}
        )

        if not status_response.ok:
            print(f'⚠️  Status check failed: {status_response.status}')
            continue

        status = status_response.json()

        # Display progress
        elapsed = attempts * 10
        print(f'[{elapsed}s] {status["pipelineStage"]} - {status["progress"]}%')

        if 'subProgress' in status:
            if 'model3d' in status['subProgress']:
                print(f'  3D Generation: {status["subProgress"]["model3d"]}%')
            if 'wearfits' in status['subProgress']:
                print(f'  WEARFITS Processing: {status["subProgress"]["wearfits"]}%')

        if status['status'] == 'completed':
            complete = True
            print('🎉 Pipeline completed!')
            print(f'AR Try-on URL: {status["tryonViewerUrl"]}')
            print(f'WEARFITS Model ID: {status["wearfitsModelId"]}')

            return {
                'tryonUrl': status['tryonViewerUrl'],
                'modelId': status['wearfitsModelId'],
                'colorId': status['wearfitsColorId']
            }
        elif status['status'] == 'failed':
            raise Exception(f'Pipeline failed: {status.get("error")}')

    raise Exception('Pipeline timeout - check status URL later')

# Usage example
if __name__ == '__main__':
    api_key = 'your_api_key_here'
    wearfits_key = 'your_wearfits_key_here'
    shoe_image = 'path/to/shoe.jpg'

    try:
        result = generate_footwear_tryon(api_key, shoe_image, wearfits_key)
        print(f'AR Try-on ready: {result["tryonUrl"]}')
    except Exception as e:
        print(f'Error: {e}')

# Submit a footwear image-to-AR-tryon job
curl -X POST \
  -H "Authorization: Bearer your_api_key_here" \
  -H "X-WEARFITS-API-Key: your_wearfits_key_here" \
  -F "image=@/path/to/shoe.jpg" \
  https://tryon-api.com/api/v1/image-to-tryon

# Response:
# {
#   "success": true,
#   "jobId": "787cb90b-1b85-417e-b351-bbeb92ffaf99",
#   "statusUrl": "/api/v1/image-to-tryon/status/787cb90b-1b85-417e-b351-bbeb92ffaf99",
#   "message": "Image-to-tryon pipeline started..."
# }

# Check job status (poll every 10 seconds)
curl -X GET \
  -H "Authorization: Bearer your_api_key_here" \
  https://tryon-api.com/api/v1/image-to-tryon/status/787cb90b-1b85-417e-b351-bbeb92ffaf99

# Example response during processing (3D generation):
# {
#   "jobId": "787cb90b-1b85-417e-b351-bbeb92ffaf99",
#   "status": "processing",
#   "pipelineStage": "3d-generation",
#   "progress": 45,
#   "subProgress": {
#     "model3d": 65
#   },
#   "message": "Generating 3D model... 65%"
# }

# Example response during WEARFITS processing:
# {
#   "jobId": "787cb90b-1b85-417e-b351-bbeb92ffaf99",
#   "status": "processing",
#   "pipelineStage": "wearfits-processing",
#   "progress": 90,
#   "subProgress": {
#     "wearfits": 45
#   },
#   "message": "Processing for AR try-on..."
# }

# Example response when completed:
# {
#   "jobId": "787cb90b-1b85-417e-b351-bbeb92ffaf99",
#   "status": "completed",
#   "pipelineStage": "completed",
#   "progress": 100,
#   "tryonViewerUrl": "https://dev.wearfits.com/tryon/dev/?object=953d38268bfd797490770cf7afd68c52~6a08a02a38",
#   "wearfitsModelId": "953d38268bfd797490770cf7afd68c52",
#   "wearfitsColorId": "6a08a02a38",
#   "result": {
#     "modelUrl": "https://...",
#     "pbrModelUrl": "https://...",
#     "renderedImageUrl": "https://..."
#   },
#   "success": true,
#   "message": "Pipeline completed! Your shoe is ready for AR try-on."
# }

# Open the tryonViewerUrl on a mobile device to see the shoe in AR!

Introduction

Authentication

👗 Apparel Try-on

POST /api/v1/tryon

Request

Request Body Parameters

Response

Error Responses

GET /api/v1/tryon/status/{jobId}

Request

Response

Error Responses

👟 Footwear Try-on

POST /api/v1/image-to-tryon

⚠️ Image Requirements (AI Validated)

Request

Request Body Parameters

Pipeline Process

Response

GET /api/v1/image-to-tryon/status/{jobId}

Response

Progress Tracking

Pipeline Stages

💻 Code Examples

👟 Footwear API Examples

POST `/api/v1/tryon`

GET `/api/v1/tryon/status/{jobId}`

POST `/api/v1/image-to-tryon`

GET `/api/v1/image-to-tryon/status/{jobId}`