Skip to main content
The Virtual Try-On API graduated from alpha to v1.0.0 with this release. Everything prior was unstable and not under any compatibility commitment — every breaking change listed below was on the table during alpha. Going forward, v1 is the stable baseline; future changes will land as additions on top, or as a clearly-numbered v2 with its own migration guide. If you were integrating against the alpha, see the Breaking changes page for migration recipes.

​
1.4.0 — 2026-06-17

Not a breaking change. The previous request shape is still accepted (deprecated). Existing integrations keep working unchanged — migrate at your own pace.

​
Changed

  • POST /try-on request shape redesigned. The canonical body is now:
    • products: [...] — an array (was the singular product object). Exactly one item for now; multi-product try-on is on the roadmap.
    • person: { image: { source: { id | url | fileKey } } } — the shopper photo (was the customer object).
    • externalUserId — opaque, no-PII attribution + GDPR key (was customerId).
    • output: { watermark, keepForDays } — result controls (was the top-level useWatermark and retentionDays). keepForDays is one of 1, 3, 7 and sets how long the generation’s stored images are kept.
  • POST /images/upload form fields renamed. externalUserId (was customerId) and keepForDays (was retentionDays). crop is unchanged. The returned imageId is passed as person.image.source.id on /try-on.

​
Deprecated

  • Previous try-on / upload shapes. The old forms — product (singular object), customer (object), top-level customerId, useWatermark, retentionDays on /try-on, and customerId / retentionDays form fields on /images/upload — are still accepted but deprecated. Prefer products[], person.image, externalUserId, output.watermark / output.keepForDays, and keepForDays in new code.

​
1.3.0 — 2026-06-17

​
Changed

  • Image references moved under a source sub-object. The customer photo on POST /try-on and each product image on POST /try-on (inline product) and POST /products now nest their reference inside source:
    • Customer: customer: { source: { id | url | fileKey } }.
    • Product images: images: [{ source: { url | fileKey }, classifications? }]. The optional classifications object now sits alongside source on each image entry.

​
Deprecated

  • Legacy flat image shape. The old top-level form — customer: { id | url | fileKey } and images: [{ url | fileKey, classifications }] — is still accepted but deprecated. Migrate to the source sub-object; prefer it in new code.

​
1.3.0 — 2026-06-25

​
Removed

  • autoClassifyImages on products. Removed from POST /products, inline /try-on product payloads, and product responses. Classification runs based on detected product type instead.

​
1.2.0 — 2026-05-18

​
Added

  • autoClassifyImages flag on products. Opt-in switch on POST /products and the inline product payload of POST /try-on. Defaults to false so generations stay as fast as possible — flip it to true on products where the smart front/back picker is worth the extra processing time.

​
Changed

  • Smarter image selection for harder categories. For some product types the engine now picks the image showing the product worn on a real person or bust rather than the flat packshot, when such an image is available. No API change required.

​
Removed

  • autoDetectImageRoles field. Replaced by autoClassifyImages (same intent, broader scope). Update any callers passing the old name.

​
1.1.0 — 2026-05-14

​
Added

  • Per-call retention on POST /images/upload and POST /try-on. New optional retentionDays body field (one of 1, 3, 7) overrides the account-level customer-retention window for that single upload. Omitting the field keeps today’s behaviour.
  • Customer identifier on uploads. POST /images/upload now accepts an optional customerId body field. When set, the upload is tracked server-side so it can later be wiped by the new GDPR endpoint. POST /try-on already accepted customerId; same semantics now apply for both endpoints.
  • GDPR delete endpoint — DELETE /tryon/v1/customers/:customerId. Deletes every customer-image and result image stored under the given customerId, anonymizes the corresponding generation rows, and removes upload tracking metadata. Idempotent, returns 204 No Content. See Delete Customer Data.
  • PRODUCT_IMAGE_FETCH_FAILED error code. When the AI pipeline can’t download a product image URL during processing, the generation transitions to FAILED with errorCode: "PRODUCT_IMAGE_FETCH_FAILED" on GET /generations/:id. Mirrors the synchronous CUSTOMER_IMAGE_FETCH_FAILED 400 already raised by POST /try-on.
  • errorCode on the generation-status response. GET /generations/:id now returns a stable errorCode alongside errorMessage whenever the failure was raised as a typed error. Switch on the code instead of parsing the message.

​
1.0.0 — 2026-05-12

First stable release. The surface is intentionally small: upload a customer photo, run a try-on, poll the result. Everything else (products, account management, watermark) is optional.

​
Added

  • Inline product field on POST /try-on. Three usage modes in one endpoint:
    • Reference an existing product by externalId.
    • Create or update a product inline (full payload), then run the generation.
    • One-shot — omit externalId and the response returns a generated ID you can re-use.
  • Customer image — three input modes on POST /try-on:
    • customer: { id } referencing a prior POST /images/upload (recommended for repeat use).
    • customer.url — server downloads on demand.
    • customer.fileKey — multipart file inline with the request.
  • Multipart product images on POST /try-on and POST /products. Mix URLs and uploaded files in the same images array.
  • crop flag on POST /tryon/v1/images/upload. Default true; pass false to preserve original framing.
  • useWatermark flag on POST /try-on. Default true; pass false to skip the account’s watermark logo for a single generation.
  • productExternalId in every /try-on response — echoes the caller’s value for named products, returns a server-generated ID for one-shots.
  • Per-product stats at GET /tryon/v1/products/:externalId/stats — totals by status and average generation time.
  • Product lifetime model:
    • Products created via POST /products are kept forever by default. Set validForDays to opt into a TTL.
    • Products created inline via /try-on live 15 days from last use (refreshed on every generation).
    • One-shot products live 7 days from last use.
    • Pass validForDays: null on an update to opt into “kept forever” later.
  • Partial updates on POST /products. Send only the fields you want to change; omitted fields stay as they were.
  • Watermark feature — composite your brand logo onto every generation. Configure once in the dashboard; opt out per-call with useWatermark: false. See Watermark.
  • Unified error responses. Every failure returns { code, message, status, details? } with a stable code from a documented enum — switch on that instead of parsing messages. Full list at Errors.

​
Changed

  • Single product field on POST /try-on replaces the older productId / externalProductId body field. The endpoint figures out reference vs. upsert vs. one-shot from what’s present.
  • Single customer object on POST /try-on replaces the old customerImageId shortcut. Exactly one of customer.id, customer.url, or customer.fileKey must be set.
  • POST /products supports partial updates. Hitting it with an existing externalId and only the field(s) you want to change merges over stored values.
  • Product responses (POST /products, GET /products, GET /products/:externalId) return the full product shape — same fields everywhere, no productId (callers reference by externalId).
  • Product images on responses are now { sourceUrl, order }. For URL-sourced images sourceUrl echoes back the URL you supplied; for multipart-uploaded images it’s an opaque internal reference you can ignore.
  • Consistent identifiers. productExternalId is now returned on every generation. The reserved prefix _anon_ is used for server-generated IDs.
  • Concurrent identical calls are safe. Parallel inline upserts with the same content resolve to a single product — no duplicates, no race conditions.

​
Removed

  • PATCH /tryon/v1/products/:externalId. Use POST /products with the fields you want to change.
  • Generation ratings (👍 / 👎) are no longer exposed on the public API — the stats endpoint returns counts and timings only.
  • GET /tryon/v1/generations (paginated list). Track your own generation ids from POST /try-on responses and poll GET /generations/:id for each one.
  • resultImageKey has been dropped from GET /generations/:id. Use resultImageUrl instead — re-fetch the endpoint when the URL expires.
  • productId has been dropped from POST /products responses. Reference products by externalId.

​
Deprecated

  • imageUrls: string[] on product upsert. Use images: [{ url }, …] instead. The old field is still accepted in v1 and will be removed in v2.

​
Documentation

​
Alpha

Unreleased. No version was assigned. The endpoint shapes, response fields, and product lifecycle rules churned regularly during this period. If you have an integration that talked to the alpha surface, the Breaking changes page covers everything you need to update.

​
Versioning

The Virtual Try-On API follows semantic versioning going forward:
  • Patch (1.0.x) — bug fixes and additive non-breaking changes.
  • Minor (1.x.0) — new endpoints, new optional fields, new response fields. Existing requests keep working.
  • Major (2.0.0+) — breaking changes. Always announced ahead of time with a parallel migration window; the old major stays available until a posted sunset date.
The current major is always reachable at /tryon/v1/*. Subscribe to release notifications at support@genlook.app.