Install on Shopify Install on WooCommerce

Get started

Introduction

Add AI virtual try-on to any store or app: send a photo of the shopper and an image of a garment, and get back a photo of the shopper wearing it.

On Shopify or WooCommerce you don't need any of this — install the app or plugin and the try-on button is added for you. The API is for everything else: custom storefronts, headless commerce, mobile apps and in-house tools.

Basics

Base URLhttps://fabricvton-api.onrender.com/api/v1
AuthAuthorization: Bearer clothsy_live_… on every request. Create your key in the Clothsy AI platform under Developer API.
Price1 credit per finished try-on. A try-on that fails is refunded automatically. Your first key comes with 20 free credits, once per account.
ImagesJPEG or PNG, up to 4 MB each. Upload a file to get an id that works for 24 hours, or pass a public HTTPS URL.
Getting the resultStart a try-on and poll for it, or use the sync endpoint, which waits up to about 55 seconds and returns the finished image in the same call.
SDKclothsy-ai for TypeScript and JavaScript, with a ready-made Next.js route and button. Or call the HTTP API from any language.
SpeedMost results are ready in under 30 seconds.
ErrorsJSON { error, code }. Branch on code. See Errors & limits.
Where to call itFrom your server only. Your key must never reach a browser or a mobile app bundle.

How it works

Optionally, your server first uploads the shopper's photo with POST /api/v1/images and receives an image id. It then starts a try-on with POST /api/v1/tryons, receives a try-on id, and polls GET /api/v1/tryons/id until the status is success and a resultUrl is returned.Your serverClothsy AIoptionalPOST /images (shopper photo file)201 { id: "img_…" }POST /tryons (photo, garment, consent)202 { id, status: "pending" }every 2–3 secondsGET /tryons/{id}{ status: "success", resultUrl }
  1. Upload the photo (optional). POST /images with the shopper's photo file returns an img_… id. Skip this if the photo already has a public HTTPS URL.
  2. Start the try-on. POST /tryons with the shopper's photo and the garment image — each as an uploaded id or a URL — plus consent: true. You get an id back straight away.
  3. Poll it. GET /tryons/{id} every 2–3 seconds until status is success or failed.
  4. Show the result. resultUrl is an image your shopper's browser can load directly for the next 24 hours.

With the SDK, the whole flow is a few lines:

tryon.ts
import { Clothsy } from "clothsy-ai";

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

const photo = await clothsy.images.upload(photoBytes, { contentType: "image/jpeg" });
const tryon = await clothsy.tryons.run({
  person: { imageId: photo.id },
  garment: { url: product.imageUrl },
  title: product.title,
  consent: true,
});

console.log(tryon.resultUrl);

Every result carries a machine-readable label saying it was made with AI. AI content label explains it, and why you should also say so on screen.

Send the product title. A title such as “Cropped denim jacket” tells the engine what kind of garment it is placing, which gives better results than an image alone.

What you need

  • A Clothsy AI account and an API key — sign in with Google, then open Developer API.
  • A server to call the API from — any language works. For JavaScript there's the TypeScript SDK, which runs on Node.js 18+, Deno, Bun and edge runtimes.
  • The shopper's agreement: they must be an adult, and must agree to their photo being processed.

Next steps

QuickstartYour first try-on in five minutes, with the SDK, curl or Python.Next.jsA route handler and a drop-in button, in three steps.TypeScript SDKUploads, try-ons, waiting, retries and typed errors.Add try-on to a custom storeThe full shape of a storefront integration.EndpointsEvery field, header and response.Full examplesWorking Node.js, Python and Next.js stores.