On this page you will find our HTTP API reference: Errors guide →

​
Run virtual try-on generation

Initiate a new virtual try-on generation by posting to the following endpoint:

​
POST try-on/run

Endpoint: https://api.getayna.com/v1/try-on/run

​
Request

curl --location 'https://api.getayna.com/v1/try-on/run' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY_HERE' \
--data '{
    "model": "ayna-1.5",
    "input": {
        "model_image": "YOUR_MODEL_IMAGE_URL_OR_BASE64_HERE",
        "garment_image": "YOUR_GARMENT_IMAGE_URL_OR_BASE64_HERE"
    }
}'

​
Request Parameters

model
​
model
string
required
Specifies the model version to use for the virtual try-on generation.Options:
  • ayna-1.5 - Latest model with high-quality results, reduced cost, and broader garment support
  • ayna-1.0 - The Ayna virtual try-on model, producing high-quality realistic try-on results
input
​
input
object
required
Contains all the input parameters for the virtual try-on generation. . Required fields:
  • model_image (string) - URL or base64 encoded string of the person/model image
  • garment_image (string) - URL or base64 encoded string of the clothing item to try on
Image Requirements:
  • Formats: JPEG, PNG, WebP
  • Input Size: 512x512 to 4095x4096 (recommended: 768x1024 for best results. Input images will be automatically scaled to 768x1024 for processing. Images with non-3:4 aspect ratios will be cropped to maintain proper proportions)
  • Output Size: 768x1024 (all generated results will be in this resolution)
  • File size: Maximum 10MB per image
  • URLs: Must be publicly accessible and return proper Content-Type headers
  • Base64: Include proper data URI format (e.g., data:image/jpeg;base64,/9j/4AAQ...)

​
Response

​
pollingUrl
string
The URL endpoint to poll for checking the generation status and retrieving results.
​
status
string
Initial status of the generation request. Can be:
  • queued - Generation has been successfully queued for processing
  • failed - Generation request failed (see error field for details)
​
error
object
Error object if the request failed, otherwise null. Contains:
  • code (string) - Error code identifier
  • message (string) - Human-readable error message
Example Response: 
{
  "pollingUrl": "https://api.getayna.com/v1/try-on/status/:id",
  "status": "queued",
  "error": null
}

​
Get generation status

Retrieve the status of a virtual try-on generation using the polling URL returned from the /run endpoint. Processing typically takes 8-15 seconds depending on image complexity and queue.

​
GET try-on/status/:id

Endpoint: https://api.getayna.com/v1/try-on/status/:id Poll this endpoint to monitor the generation’s progress and retrieve the final output once available. Use the pollingUrl returned from the /run endpoint.

​
Request

curl --location 'https://api.getayna.com/v1/try-on/status/:id' \
--header 'Authorization: Bearer YOUR_API_KEY_HERE'

​
Request Parameters

No additional parameters required. Use the complete pollingUrl returned from the /run endpoint to check the generation status.

​
Response

The response will return the generation status, output, and error fields.
Status Types
​
status
string
Current status of the generation. Can be one of:
  • queued - Generation is waiting in the processing queue
  • processing - Generation is currently being processed
  • completed - Generation has finished successfully
  • failed - Generation has failed (see error field for details)
​
output
object
Object containing the result image URL when status is “completed”, otherwise null. URLs are valid for 24 hours.
​
error
object
Error object if the generation failed, otherwise null. Contains:
  • code (string) - Error code identifier
  • message (string) - Human-readable error message
Example Responses
Generation queued: 
{
  "status": "queued",
  "output": {
    "image": null
  },
  "error": null
}
Generation processing: 
{
  "status": "processing",
  "output": {
    "image": null
  },
  "error": null
}
Generation completed: 
{
  "status": "completed",
  "output": {
    "image": "https://cdn.getayna.com/outputs/1752555896712.png"
  },
  "error": null
}
Generation failed: 
{
  "status": "failed",
  "output": {
    "image": null
  },
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid image format or unsupported garment type"
  }
}

​
Output

The virtual try-on generation produces high-quality output images with the following specifications:
Resolution: 768x1024 pixelsAspect Ratio: 3:4 (portrait orientation)Format: PNGQuality: High-resolution results optimized for virtual try-on applicationsAvailability: Output images are accessible via URL for 24 hours after generation. It is recommended to save the image to your own storage after generation.All input images are automatically scaled and processed to generate consistent 768x1024 output regardless of input dimensions. Images with non-3:4 aspect ratios will be cropped to maintain the proper 3:4 proportions during processing.

​
Rate Limits

  • /run - Up to 30 requests per 60 seconds
  • /status - Up to 1 request per 2 seconds per try-on generation

​
Best Practices

  1. Polling frequency: Poll the status endpoint every 2-5 seconds until completion to balance responsiveness with API usage
  2. Image requirements:
    • Use high-quality images (minimum 512x512 pixels, recommended 768x1024)
    • Supported aspect ratios: 3:4 (Images with non-3:4 aspect ratios will be cropped to maintain proper proportions)
    • Ensure model image shows a clear view of the person
    • Garment image should be well-lit and unobstructed
  3. Error handling: Always check the error field in responses and handle failures gracefully
  4. Retry logic: Implement exponential backoff for rate limit errors (429 status)

​
Privacy

Input images and generated outputs are automatically deleted from our systems after 24 hours for privacy and security.