Direct API

For custom UI implementations where you want to build your own modal, upload flow, and UI state machine, you can call the REST API directly and skip the SDK altogether.

Note

Most integrators should use the THGVTO SDK. Reach for the raw API only when you need a fully bespoke UI that the SDK’s modal can’t express.

Flow

1. Upload — POST /upload-photo with the user’s photo, receive a ref
2. Generate — POST /try-on with { personImageRef, modelImageUrl }, receive the result image
3. Feedback (optional) — POST /feedback with the requestId from generation

All endpoints require an X-API-Key header. See the API Endpoints reference for request/response schemas.

Minimal JavaScript example

const API = 'https://api-nonprod.thg.dev/agentic-commerce/v1/vto';
const API_KEY = 'your-api-key';

async function uploadPhoto(base64) {
  const res = await fetch(`${API}/upload-photo`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
    body: JSON.stringify({ personImageBase64: base64, processBackground: false }),
  });
  if (!res.ok) throw new Error(`Upload failed: ${res.status}`);
  return res.json(); // { ref, sessionId, processedImageBase64, validation? }
}

async function generate(personImageRef, modelImageUrl, product) {
  const res = await fetch(`${API}/try-on`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
    body: JSON.stringify({
      personImageRef,
      modelImageUrl,
      productName: product?.name,
      productUrl: product?.url,
    }),
  });
  if (!res.ok) throw new Error(`Generate failed: ${res.status}`);
  return res.json(); // { requestId, imageBase64, shareUrl }
}

// Usage
const { ref } = await uploadPhoto(myBase64);
const { imageBase64, shareUrl } = await generate(
  ref,
  'https://cdn.example.com/products/shirt.jpg',
  { name: 'Blue Oxford Shirt', url: location.href },
);

Session persistence

The server returns a sessionId from /upload-photo. Persist it on the client (localStorage, cookie, etc.) and pass it as x-session-id on subsequent calls to keep analytics, history, and cache coherent across page navigations. The SDK does this automatically; if you’re rolling your own, you’ll need to handle it yourself.

Caching

The server caches try-on results keyed on (personImageRef, modelImageUrl). Calling /try-on again with the same inputs returns the cached result without re-running the pipeline. The SDK exposes this via product.getImage().