AI Virtual Try-On Actor

An Apify Actor that generates virtual try-on images using AI. Provide a human image and a garment image; the Actor returns a realistic visualization of how the clothing would look on the person.

---

Table of Contents

• Features
• Input
• Output
• Quick Start
• Configuration
• Usage Examples
• Integration
• Technical Details
• Troubleshooting
• Resources

---

Features

• Realistic try-on images – Combines human and garment photos via the MultipleWords API
• Body part options – Upper body, lower body, or dresses
• Flexible input – File upload, URLs, base64, or local file paths
• Structured output – Dataset with image URLs and metadata (see Output schema)
• Error handling – Validation, timeouts (4 min), and clear error messages

---

Input

The Actor accepts JSON input with these parameters:

Parameter	Type	Required	Description
for_body_part	string	Yes	"upper_body", "lower_body", or "dresses"
human_image	string	Yes	Human/person image: file upload key, URL, base64, or file path
garment_image	string	Yes	Garment image: file upload key, URL, base64, or file path

Notes: user_id and isPro are fixed in the Actor (663559 and 1) and are not in the input schema.

Body part

• upper_body – Shirts, jackets, tops
• lower_body – Pants, skirts, shorts
• dresses – Dresses and full-body garments

Image formats

• Apify Console – Upload files; input will contain the storage key
• URL – e.g. "https://example.com/person.jpg"
• File path – e.g. "./images/human.jpg" (local runs)
• Base64 – e.g. "data:image/jpeg;base64,..."

Use clear, front-facing photos. Formats: JPEG, PNG, WebP.

---

Output

Results are written to the default dataset. Each item has:

Field	Type	Description
success	boolean	Whether generation succeeded
status	number	API status (1 = success)
image_url	string	URL of the generated try-on image
user_image_url	string	URL of the processed human image
garment_image_url	string	URL of the processed garment image
details	object	Extra API metadata (id, timestamps, etc.)
message	string	Status message

The Actor defines an output schema so the run Output tab in Apify Console shows these fields in a table.

---

Quick Start

1. Run locally

npm install
apify run

Use default input (prefill) or set storage/key_value_stores/default/INPUT.json (see Configuration).

2. Deploy and run on Apify

apify login
apify push

In Apify Console → Actors → AI Virtual Try-On: upload Human Image and Garment Image, choose Body Part, then Start.

3. Call via API

curl -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~ai-virtual-try-on/run-sync" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "for_body_part": "upper_body",
    "human_image": "https://example.com/person.jpg",
    "garment_image": "https://example.com/shirt.jpg"
  }'

---

Configuration

Local input file

Create or edit storage/key_value_stores/default/INPUT.json:

{
  "for_body_part": "upper_body",
  "human_image": "./images/human.jpg",
  "garment_image": "./images/garment.jpg"
}

Or use URLs:

{
  "for_body_part": "upper_body",
  "human_image": "https://example.com/person.jpg",
  "garment_image": "https://example.com/shirt.jpg"
}

Prefilled input (automated tests)

The input schema defines prefill values so the Actor can be run with default input (e.g. for Apify’s automated health checks). You can override any field when running the Actor.

---

Usage Examples

Apify Client (Node.js)

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_API_TOKEN' });

const input = {
  for_body_part: 'upper_body',
  human_image: 'https://example.com/person.jpg',
  garment_image: 'https://example.com/shirt.jpg'
};

const run = await client.actor('YOUR_USERNAME/ai-virtual-try-on').call(input, {
  waitSecs: 120
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0].image_url);

See test-with-apify-client.js and test-upload-files.js for full examples.

Minimal input (prefill)

If you run with no custom input, the Actor uses prefilled values (body part and placeholder image URLs). Replace with your own images for best results.

---

Integration

• Make (Integromat) – Trigger try-on when new products are added; send results to storage or email.
• Zapier – Run from e‑commerce events; add try-on images to listings; notify via Slack/email.
• Custom apps – Use the Apify API to integrate try-on into your platform or batch process catalogs.

---

Technical Details

• Runtime: Node.js 18+
• SDK: Apify v3.5.2+
• API: POST https://shorts.multiplewords.com/mwvideos/api/generate_try_on_image (multipart/form-data)
• Timeout: 4 minutes per request (run must finish within 5 minutes for automated tests)
• Logging: Uses apify/log; supports graceful abort on stop

---

Troubleshooting

Issue	What to do
"human_image is required"	Ensure input has human_image and garment_image (or use prefill).
"API request timed out"	Service may be busy; retry or use smaller images.
API returns error status	Check image quality and format; ensure URLs are accessible if using URLs.
Automated test failures	Prefill uses default image URLs; if the external API often fails, consider contacting support@apify.com for test exclusion.

More on input formats: FILE_UPLOAD_GUIDE.md, HOW_TO_UPLOAD_FILES.md, INPUT_EXAMPLE.md.

---

Resources

• Apify SDK (JavaScript)
• Apify Platform
• Actor output schema
• Apify Community

---

Built with Apify SDK.