Documentation

Integrate photorealistic virtual try-on into your e-commerce flow with a single API call. This guide covers authentication, endpoints, and best practices.

Quick Start

Get a try-on result in under 30 seconds. You'll need your API key from the dashboard.

curl -X POST https://api.seamstress.io/v1/try-on \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "user_photo_abc123",
    "garment_id": "sku_leather_jacket_001",
    "drape_physics": true
  }'

Response: A JSON object with a result_url pointing to the generated image.

Authentication

All API requests require authentication via Bearer token. Generate your keys in the dashboard.

Authorization: Bearer sk_live_xxxxxxxxxxxx

Use sk_test_ for sandbox mode. Test keys have rate limits but no billing.

Try-On Endpoint

The core endpoint for generating virtual try-on images.

POST/v1/try-on

Base URL: https://api.seamstress.io

Typical latency: 80–200ms. Images are available for 24 hours.

Parameters

Parameter	Type	Description
model_id	string	ID of the model photo (upload via /v1/uploads or use a catalog ID)
garment_id	string	Product SKU or garment asset ID from your catalog
fit	string	`slim`, `regular`, or `oversized`. Default: regular
tuck	boolean	Simulate tucking the garment in. Default: false
drape_physics	boolean	Enable fabric physics for realistic draping. Slightly increases latency.

Response

{
  "id": "ton_abc123xyz",
  "result_url": "https://cdn.seamstress.io/results/abc123.jpg",
  "status": "succeeded",
  "latency_ms": 127,
  "created_at": "2025-02-14T12:00:00Z"
}

Examples

JavaScript / Node.js

const response = await fetch('https://api.seamstress.io/v1/try-on', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SEAMSTRESS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model_id: 'user_123',
    garment_id: 'sku_592',
    fit: 'oversized',
    drape_physics: true,
  }),
});

const { result_url } = await response.json();
console.log('Try-on ready:', result_url);

Python

import requests

response = requests.post(
    "https://api.seamstress.io/v1/try-on",
    headers={"Authorization": f"Bearer {os.environ['SEAMSTRESS_API_KEY']}"},
    json={
        "model_id": "user_123",
        "garment_id": "sku_592",
        "fit": "slim",
        "drape_physics": True,
    },
)
data = response.json()
print(data["result_url"])

Error Handling

Errors return appropriate HTTP status codes and a JSON body with code and message.

{
  "code": "invalid_garment",
  "message": "Garment ID 'invalid' not found in catalog"
}

Code	Description
invalid_api_key	Authentication failed
rate_limit_exceeded	Too many requests
invalid_model	Model photo rejected or expired
invalid_garment	Garment not in catalog

Need help? Contact support or join our Discord.