Guide

Uploading images

The API can take images in two ways: as a public HTTPS URL, or as a file you upload first. For shopper photos, uploading is usually simpler and more private.

Why upload

A try-on needs a photo of the shopper, and that photo normally starts life as a file in your server's memory. To pass it by URL you would have to store it somewhere, sign a short-lived link, make sure the link doesn't redirect, and delete the file afterwards. Uploading skips all of that: send the bytes to POST /images, get back an id, and use the id in the try-on.

You can mix the two in one request. A typical storefront uploads the shopper's photo and passes the garment as the product image URL it already has.

One photo, many garments

An uploaded image id isn't used up by a try-on. Upload a shopper's photo once and reuse the id for every item they want to see — a whole outfit, or everything they browse in one visit. Each try-on still costs one credit; the upload itself costs nothing.

import { Clothsy } from "clothsy-ai";

const clothsy = new Clothsy(); // reads CLOTHSY_API_KEY

// Upload the shopper's photo once…
const photo = await clothsy.images.upload(photoBytes, { contentType: "image/jpeg" });

// …then try on as many garments as you like in the next 24 hours.
for (const product of outfit) {
  const look = await clothsy.tryons.run({
    person: { imageId: photo.id },
    garment: { url: product.imageUrl },
    title: product.title,
    consent: true,
  });
  console.log(product.title, look.resultUrl);
}

Each account can start 12 try-ons a minute. Running them one after another, as above, stays well inside that; if you start several at once, queue anything beyond the limit rather than sending it all together.

Limits

• JPEG or PNG only, up to 4 MB per file. Resizing to about 1600 px on the long side keeps photos well under.
• 30 uploads a minute per account.
• An id works only for the account that uploaded it.
• An id works for 24 hours, until the expiresAt time in the upload response. After that it's gone for good — using it returns 400 INVALID_IMAGE_ID, and you need to upload the file again.

Privacy and deletion

Uploaded files are deleted automatically, at the latest 35 days after upload, and an id can never be revived once it has expired. There is nothing for you to clean up. Even so, only upload what a try-on needs:

• Ask for the shopper's consent before you upload their photo, not after.
• Re-encode photos to JPEG before sending them. That drops camera metadata such as GPS location — the browser code in the custom store guide does it for you.
• Mention in your privacy policy that shopper photos are sent to a virtual try-on service. Ours is at shopper privacy if you'd like to link to it.