Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.genlook.app/docs/llms.txt

Use this file to discover all available pages before exploring further.

The 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.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 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.