Get started

Quickstart

Your first try-on in about five minutes: create a key, upload a photo, and get back an image of that person wearing a garment.

Every step has three versions — the TypeScript SDK, plain curl, and Python. Pick one tab and follow it through.

1. Create your API key

1. Sign in to the Clothsy AI platform with Google.
2. Open Developer API and click Create API key. Your first key adds 20 free credits to the account.
3. Copy the key straight away — it starts with clothsy_live_ and is shown only once. Store it as a secret on your server:

export CLOTHSY_API_KEY="clothsy_live_..."

2. Install

npm install clothsy-ai

The SDK needs Node.js 18 or later (or Deno, Bun, or an edge runtime) and has no dependencies. Using Next.js? The Next.js guide gets you a working button even faster.

3. Upload the shopper's photo

Save a JPEG or PNG under 4 MB as shopper.jpg — a clear, full-length photo of one adult who has agreed to it being used. Upload it to get an image id. Uploading is free, and the id works for 24 hours.

// tryon.mjs
import { readFile } from "node:fs/promises";
import { Clothsy } from "clothsy-ai";

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

const photo = await clothsy.images.upload(await readFile("shopper.jpg"), {
  filename: "shopper.jpg",
  contentType: "image/jpeg",
});
console.log(photo.id);

{
  "id": "img_5Hq2mV8xKc3TnR7w",
  "expiresAt": "2026-10-01T09:30:00.000Z"
}

Already have the photo at a public HTTPS URL? You can skip the upload and send personImageUrl (or person: { url } in the SDK) instead. Uploading images compares the two.

4. Create the try-on

Send the photo's id, a garment image and consent: true. This uses the sync endpoint, which waits for the result — usually well under 30 seconds — and answers with the finished image.

// tryon.mjs, continued
const tryon = await clothsy.tryons.run({
  person: { imageId: photo.id },
  garment: { url: "https://your-cdn.example.com/denim-jacket.jpg" },
  title: "Cropped denim jacket",
  consent: true,
});
console.log(tryon.resultUrl);

{
  "id": "7f3c2a9e-1d4b-4c1e-9a55-2b8f0c6d4e10",
  "status": "success",
  "resultUrl": "https://fabricvton-api.onrender.com/i/eyJ..."
}

The Idempotency-Key makes retries safe: sending the same key again returns the same try-on instead of starting — and paying for — a second one. The SDK sets one for you.

5. If it isn't done yet, poll

The sync endpoint waits about 55 seconds at most. If the image isn't ready by then you get 202 with the try-on's id instead, and you carry on by polling every 2–3 seconds.

{
  "id": "7f3c2a9e-1d4b-4c1e-9a55-2b8f0c6d4e10",
  "status": "pending",
  "pollUrl": "/api/v1/tryons/7f3c2a9e-1d4b-4c1e-9a55-2b8f0c6d4e10"
}

// Nothing to add: run() keeps polling until the try-on is finished.
// If you'd rather start now and collect the result later:
const started = await clothsy.tryons.create({
  person: { imageId: photo.id },
  garment: { url: "https://your-cdn.example.com/denim-jacket.jpg" },
  title: "Cropped denim jacket",
  consent: true,
});
const done = await clothsy.tryons.waitFor(started.id);
console.log(done.resultUrl);

In a storefront you'll usually skip the sync endpoint and poll from the start, so your server can answer the browser at once. Add try-on to a custom store shows that pattern.

6. Show it

resultUrl is a JPEG or PNG image you can put straight into an <img> tag. It works for 24 hours; download and store it yourself if you need it for longer. When you show it to shoppers, add a small “AI-generated try-on” caption — here's why.

Next: see the whole SDK, or how the pieces fit into a real storefront in Add try-on to a custom store.