API Documentation

Introduction

Welcome to the TryonAPI documentation.

Our API allows you to generate virtual try-on images by combining person and garment photos. 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.

Authentication

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

Authorization: Bearer <YOUR_API_KEY>

API Endpoints

The following endpoints are available for virtual try-on operations.

POST /api/v1/tryon

Submits a new virtual try-on job.

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.

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.
  • 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.
  • 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. Failures can be due to invalid input (see specific errorCode values), processing errors, or internal issues.

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.

Code Examples

Examples of how to use the API in different programming languages.

// Example using fetch API async function generateTryOn(apiKey, personImageUrl, garmentImageUrl) { // Create FormData const formData = new FormData(); formData.append('person_images', personImageUrl); formData.append('garment_images', garmentImageUrl); // 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.resultImageUrl; 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): # Prepare the request headers = { 'Authorization': f'Bearer {api_key}' } files = { 'person_images': open(person_image_path, 'rb'), 'garment_images': open(garment_image_path, 'rb') } # Submit job response = requests.post( 'https://your-domain.com/api/v1/tryon', headers=headers, files=files ) 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['resultImageUrl'] 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 # 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