PrimeStyle VTO API

Try-On Balance & Rate Limits

Each successful try-on deducts one token from your account. Sizing endpoints are currently free and metered only by rate limits. Every POST /api/v1/tryon response includes tryOnsUsed and newBalance so your dashboard can show the running total.

Poll Try-On Status

curl https://myaifitting.com/api/v1/tryon/status/65c8d1a4e2b4f5d3c8a91234 \
  -H "Authorization: Bearer $PRIMESTYLE_API_KEY"

{
  "galleryId": "65c8d1a4e2b4f5d3c8a91234",
  "status": "completed",
  "imageUrl": "https://res.cloudinary.com/.../result.jpg",
  "message": "Try-on ready"
}

status is one of processing, completed, or failed. The imageUrl is populated only when the job completes successfully.

Server-Sent Events Stream

curl -N "https://myaifitting.com/api/v1/tryon/stream?key=$PRIMESTYLE_API_KEY"

Uploading Images

The try-on endpoint does not require a separate upload step. Pass images either as a public URL that PrimeStyle can fetch, or as a data:image/jpeg;base64,… URI. The SDK helpers compressImage and isValidImageFile can prepare a user file before posting.

Recommend a Size

curl -X POST https://myaifitting.com/api/v1/sizing/recommend \
  -H "Authorization: Bearer $PRIMESTYLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "exact",
    "sizingUnit": "cm",
    "product": {
      "title": "Linen Oxford Shirt",
      "description": "Regular fit, 100% linen."
    },
    "measurements": {
      "chest": 102,
      "waist": 86,
      "height": 180,
      "weight": 78
    }
  }'

{
  "recommendedSize": "M",
  "tightSize": "S",
  "looseSize": "L",
  "confidence": "high",
  "reasoning": "Chest 102cm falls in the middle of the M band (100-104cm).",
  "internationalSizes": { "US": "M", "EU": "50", "UK": "M" },
  "unit": "cm"
}

Estimate Body Measurements

# Normal mode — estimate from height/weight/gender + optional shape answers
curl -X POST https://myaifitting.com/api/v1/sizing/estimate \
  -H "Authorization: Bearer $PRIMESTYLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "height": 180,
    "weight": 78,
    "heightUnit": "cm",
    "weightUnit": "kg",
    "gender": "male",
    "age": 32,
    "bodyType": "average",
    "chestProfile": "average",
    "midsectionProfile": "flat",
    "hipProfile": "average",
    "requiredFields": ["chest", "waist", "hips", "shoulderWidth"]
  }'
# Snap mode — estimate from a body photo alone
curl -X POST https://myaifitting.com/api/v1/sizing/estimate \
  -H "Authorization: Bearer $PRIMESTYLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "snapMode": true,
    "bodyImage": "https://cdn.example.com/body.jpg",
    "requiredFields": ["chest", "waist", "hips"]
  }'

{
  "estimates": {
    "chest": 102,
    "waist": 86,
    "hips": 98,
    "shoulderWidth": 46
  },
  "method": "llm",
  "unit": "cm",
  "detectedGender": "male"
}

Parse a Size Guide

# 1. Raw HTML — backend parses it with an LLM
curl -X POST https://myaifitting.com/api/v1/sizing/sizeguide \
  -H "Authorization: Bearer $PRIMESTYLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": { "title": "Linen Oxford Shirt" },
    "sizeGuideRaw": "<table>...</table>"
  }'
# 2. Pre-structured JSON — no parsing needed
curl -X POST https://myaifitting.com/api/v1/sizing/sizeguide \
  -H "Authorization: Bearer $PRIMESTYLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": { "title": "Linen Oxford Shirt" },
    "sizeGuideData": {
      "headers": ["Size", "Chest (cm)", "Waist (cm)"],
      "rows": [["S","92-96","76-80"], ["M","100-104","84-88"]]
    }
  }'
# 3. Image URLs only — backend uses vision to extract the table
curl -X POST https://myaifitting.com/api/v1/sizing/sizeguide \
  -H "Authorization: Bearer $PRIMESTYLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": { "title": "Linen Oxford Shirt" },
    "sizeChartImages": [
      "https://cdn.example.com/size-chart-men.jpg"
    ]
  }'

{
  "found": true,
  "title": "Men's Shirt Size Guide",
  "headers": ["Size", "Chest (cm)", "Waist (cm)"],
  "rows": [
    ["S",  "92-96",  "76-80"],
    ["M",  "100-104","84-88"],
    ["L",  "108-112","92-96"]
  ],
  "sections": []
}

Error Codes

Guest Try-On (no auth)

For marketing demos and landing pages, a public endpoint accepts one free try-on per IP address without an API key. It is otherwise identical to the authenticated version. There is a matching GET /api/public/tryon/status/:jobId.

curl -X POST https://myaifitting.com/api/public/tryon \
  -H "Content-Type: application/json" \
  -d '{
    "modelImage": "https://cdn.example.com/user.jpg",
    "garmentImage": "https://cdn.example.com/shirt.jpg"
  }'

React Component: <PrimeStyleTryon />

The React component renders a launch button and, when clicked, a full-screen modal that walks the user through profile creation, sizing, and try-on. A single prop — productImage — is enough to ship.

import { PrimeStyleTryon } from "@primestyleai/tryon/react";

import { PrimeStyleTryon } from "@primestyleai/tryon/react";
export function ProductTryOnButton({ product }) {
  return (
    <PrimeStyleTryon
      productImage={product.image}
      productTitle={product.title}
      productId={product.sku}
      buttonText="See it on you"
      apiUrl={process.env.NEXT_PUBLIC_PRIMESTYLE_API_URL}
      locale="en"
      showPoweredBy
      onOpen={() => track("tryon_open", { sku: product.sku })}
      onUpload={(file) => track("tryon_upload", { size: file.size })}
      onProcessing={(jobId) => track("tryon_processing", { jobId })}
      onComplete={({ jobId, imageUrl }) => {
        track("tryon_complete", { jobId });
        analytics.setResult(imageUrl);
      }}
      onError={(err) => track("tryon_error", err)}
    />
  );
}

Customization

Three layers, in order of precedence (top wins):

• •classNames — map of Tailwind/CSS classes for specific slots (button, modal, footer, etc.).
• •buttonStyles and modalStyles — typed objects for the common tweaks (colors, border, radius, hover).
• •className + style — last-resort overrides on the launch button.

<PrimeStyleTryon
  productImage={product.image}
  buttonStyles={{
    background: "#111",
    color: "#fff",
    borderRadius: 0,
    hoverBackground: "#2154EF",
  }}
  modalStyles={{ accent: "#2154EF" }}
  classNames={{ launchButton: "font-serif uppercase tracking-widest" }}
/>

Callbacks

All callbacks are optional and fire in this order during a successful flow:

Headless Sizing

If you don't want the bundled modal, three primitives let you build your own UI on top of the same sizing engine. All of them are pure client-side calls against the PrimeStyle API and use whatever profile is currently active in localStorage.

import { recommendForProduct } from "@primestyleai/tryon";
const rec = await recommendForProduct({
  apiUrl: "https://myaifitting.com",
  product: {
    title: "Linen Oxford Shirt",
    description: "Regular fit, 100% linen.",
  },
  sizingUnit: "cm",
});
if (rec) {
  console.log(rec.recommendedSize, rec.confidence, rec.reasoning);
}

import { estimateFullMeasurements } from "@primestyleai/tryon";
const result = await estimateFullMeasurements({
  apiUrl: "https://myaifitting.com",
  height: 180,
  weight: 78,
  heightUnit: "cm",
  weightUnit: "kg",
  gender: "male",
  requiredFields: ["chest", "waist", "hips"],
});
console.log(result?.estimates, result?.unit);

import { usePrimeStyleSize } from "@primestyleai/tryon/react";
function SizeRecommendation({ product }) {
  const { data, loading, error } = usePrimeStyleSize({
    product: { title: product.title, description: product.description },
    sizingUnit: "cm",
  });
  if (loading) return <p>Measuring&hellip;</p>;
  if (error) return <p>Couldn&apos;t compute a size.</p>;
  if (!data) return <p>Set up your profile to see a size.</p>;
  return (
    <div>
      <strong>Recommended: {data.recommendedSize}</strong>
      <p>{data.reasoning}</p>
    </div>
  );
}

Web Component (Coming Soon)

Profile Storage (localStorage)

import {
  getProfiles,
  getActiveProfile,
  getActiveProfileId,
  setActiveProfileId,
  saveProfiles,
  updateProfile,
  updateProfileMeasurements,
  addSizeToHistory,
  getCachedSize,
} from "@primestyleai/tryon";
// Read the current active profile (or null).
const profile = getActiveProfile();
// Switch profiles.
setActiveProfileId("profile-2");
// Update measurements after the user edits them.
updateProfileMeasurements(profile.id, {
  chest: 104,
  waist: 88,
}, "cm");
// Look up a cached size recommendation for a product.
const cached = getCachedSize(profile, "sku-12345");

Environment Variables

The SDK itself does not read the API key from any env var; it hits whatever URL you point it at. Proxy the key through your backend so end users never see it.

Internationalization (i18n)

Pass a locale via the locale prop (or locale attribute on the web component). The SDK ships with a set of built-in translations and will fall back to English for missing keys.

Using Your Own Size Guide

If you already have structured size data, pass it directly to sizeGuideData. The SDK will skip the call to /api/v1/sizing/sizeguide and feed your table straight into the recommender.

import { PrimeStyleTryon } from "@primestyleai/tryon/react";
export function ProductButton({ product }) {
  return (
    <PrimeStyleTryon
      productImage={product.image}
      productTitle={product.title}
      productId={product.sku}
      sizeGuideData={{
        headers: ["Size", "Chest (cm)", "Waist (cm)"],
        rows: [
          ["S",  "92-96",   "76-80"],
          ["M",  "100-104", "84-88"],
          ["L",  "108-112", "92-96"],
        ],
      }}
    />
  );
}

If all you have is raw HTML (for example, the innerHTML of a merchant's existing size-guide panel), call the parser endpoint once at build time and cache the normalized structure with your product:

// 1. Normalize raw HTML once, cache the result on your product.
const guide = await fetch(
  "https://myaifitting.com/api/v1/sizing/sizeguide",
  {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      product: { title: product.title },
      sizeGuideRaw: product.sizeGuideHtml,
    }),
  },
).then((r) => r.json());
// 2. Pass the normalized guide back to PrimeStyleTryon:
<PrimeStyleTryon
  productImage={product.image}
  productTitle={product.title}
  sizeGuideData={guide}
/>

Listening to Try-On Events

Wire the component's callbacks into your analytics to understand the funnel (opens → uploads → completes) and to react to the final image (cache it, show a "looks great" prompt, etc.).

<PrimeStyleTryon
  productImage={product.image}
  productTitle={product.title}
  productId={product.sku}
  onOpen={() => analytics.track("tryon_open")}
  onUpload={(file) =>
    analytics.track("tryon_upload", { size: file.size, type: file.type })
  }
  onProcessing={(jobId) => analytics.track("tryon_processing", { jobId })}
  onComplete={({ jobId, imageUrl }) => {
    analytics.track("tryon_complete", { jobId });
    setResultImage(imageUrl);
  }}
  onError={({ message, code }) =>
    analytics.track("tryon_error", { message, code })
  }
/>

Image Best Practices

// Accepted image sources for modelImage / garmentImage:
// - Public HTTPS URL:
"https://cdn.example.com/products/shirt.jpg"
// - Data URI (base64):
"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
// - Helpers for browser-side files:
import { compressImage, isValidImageFile } from "@primestyleai/tryon";
if (!isValidImageFile(file)) throw new Error("Unsupported image");
const compressed = await compressImage(file, { maxDimension: 1600 });

Loading States

Try-ons typically complete in 15-20 seconds. To keep the UI responsive:

• •Show an optimistic state as soon as onProcessing(jobId) fires.
• •Prefer /api/v1/tryon/stream (SSE) over polling; it typically shaves 1-3 seconds off the perceived latency.
• •Fall back to polling /status/:jobId every 3 seconds if SSE is blocked (some corporate proxies strip it).
• •On failed, show a short retry affordance — failed jobs are refunded automatically.

Privacy Policy

This Privacy Policy describes how PrimeStyleAI processes information in connection with the Services. In most cases, Customer is the data controller for End User data collected on Customer's properties, and PrimeStyleAI acts as a data processor solely to generate Outputs and operate the Services.

Cookie Policy

PrimeStyleAI uses cookies and similar technologies primarily to operate the developer portal and maintain security.

GDPR Compliance

PrimeStyleAI is designed with privacy-by-design principles. In most cases, Customer is the data controller and PrimeStyleAI acts as a processor. We support execution of a Data Processing Addendum (DPA), including Standard Contractual Clauses where appropriate.

2. Details of Processing

Annex 1 describes the subject matter, duration, nature and purpose of processing, types of personal data, and categories of data subjects.

3. Processor Obligations

• •Process personal data only on documented instructions from Customer, unless required by law.
• •Ensure persons authorized to process personal data are bound by confidentiality obligations.
• •Implement appropriate technical and organizational measures to protect personal data.
• •Assist Customer with responding to data subject requests, taking into account the nature of processing.
• •Assist Customer with DPIAs and consultations with regulators to the extent required and reasonably available.

4. Security Measures

Processor maintains reasonable measures appropriate to the risk. Annex 2 lists baseline controls.

5. Subprocessors

6. International Transfers

Where personal data originating in the EEA/UK/Switzerland is transferred to a country without an adequacy decision, the Parties will implement appropriate safeguards, such as the EU Standard Contractual Clauses (SCCs) and/or the UK Addendum, typically incorporated by reference through this DPA or an exhibit.

7. Personal Data Breach

8. Deletion & Return

Upon termination of the Services, Processor will delete or return personal data as requested by Customer, subject to applicable law and reasonable backups/archival practices. Transient user images are not intended to be stored persistently by default.

9. Audits

Upon reasonable prior notice and no more than once annually, Customer may audit Processor's compliance with this DPA to the extent necessary and proportionate, subject to confidentiality and security constraints. Processor may satisfy audit requests by providing summaries of controls, third-party reports (if available), or other reasonable evidence of compliance.