Skip to main content
POST
/
tryon
/
v1
/
try-on
curl -X POST "https://api.genlook.app/tryon/v1/try-on" \
  -H "x-api-key: gk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product": { "externalId": "shirt-42" },
    "customer": { "id": "retention-7d/.../customer/20260512-….jpeg" }
  }'

{
  "generationId": "cm8gen456xyz",
  "status": "PENDING",
  "productExternalId": "shirt-42"
}

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.

Creates a virtual try-on generation. Runs asynchronously — poll Generation Status for the result. Each generation consumes 1 credit. The body has two parts: a product object that describes what to try on, and a customer image (either pre-uploaded or shipped inline).

​
Product

product works three ways:
  • Reference an existing product — pass { "externalId": "..." } only. Cheapest call (~50 bytes on the wire).
  • Describe a product inline — pass { "externalId": "...", "title": ..., "description": ..., "images": [...] }. Creates the product if it’s new; updates it if it’s not. Inline-created products live for 15 days from their last use; the server refreshes the timer on every generation, so an actively-used product never expires.
  • One-shot — omit externalId. The server returns a generated ID in the response under productExternalId that you can pass back if you want to reference the same product later. One-shot products live for 7 days from their last use.
​
product
object
required

​
Customer image

​
customer
object
required
The customer photo. Exactly one of id, url, or fileKey must be set.
​
customerId
string
Optional identifier of your own (e.g. your user ID) for your own tracking. When set, the generation — and the customer image uploaded as part of this call — can be wiped on demand via DELETE /customers/:customerId.
​
retentionDays
integer
Optional retention preset for the customer image stored for this generation. One of 1, 3, 7. Defaults to your account’s configured customer-retention window. Ignored when customer.id references an already-uploaded image (the existing storage path is reused).
​
useWatermark
boolean
default:"true"
Composite your account’s watermark logo onto the result. Set false to skip for this generation. No-op if your account has no logo configured. See Watermark.
  1. Upload the customer image once via POST /images/upload — gets you an imageId you can reuse.
  2. Call /try-on with { product: { externalId }, customer: { id: imageId } } for repeat generations against known products, or with the full inline product when introducing a new SKU.
The inline customer.url and customer.fileKey paths are convenient one-shot conveniences but they re-download/re-upload on every call. Stick to /images/upload once you’re in steady state.

​
Examples

curl -X POST "https://api.genlook.app/tryon/v1/try-on" \
  -H "x-api-key: gk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product": { "externalId": "shirt-42" },
    "customer": { "id": "retention-7d/.../customer/20260512-….jpeg" }
  }'

​
Response

​
generationId
string
required
Poll GET /generations/:id every 2s until status is COMPLETED or FAILED.
​
status
string
required
Initial status: PENDING.
​
productExternalId
string
The product’s external ID. Echoes back the value you sent for named calls; on one-shot calls it’s a server-generated ID you can store and re-use to reference the same product later.
{
  "generationId": "cm8gen456xyz",
  "status": "PENDING",
  "productExternalId": "shirt-42"
}

​
Errors

CodeHTTPMeaning
PRODUCT_NOT_FOUND404The referenced externalId doesn’t exist (or has expired). Retry with a full inline payload.
PRODUCT_IMAGES_REQUIRED400One-shot call (no externalId) without any image.
CUSTOMER_IMAGE_REQUIRED400customer is missing.
CUSTOMER_IMAGE_FETCH_FAILED400customer: { url } could not be downloaded — DNS fail, host unreachable, or non-2xx status.
MULTIPART_FILE_NOT_FOUND400A fileKey from data doesn’t appear in the multipart payload.
VALIDATION_FAILED400Request body failed validation — see details[] for the offending fields.
INSUFFICIENT_CREDITS402Account is out of credits.
RESERVED_EXTERNAL_ID409product.externalId starts with _anon_, which is reserved for server-generated IDs.
Full catalog at Errors. If a reference call returns PRODUCT_NOT_FOUND, the product has fallen out of cache — retry with the full inline payload to recreate it. No sync loop required.

​
Watermarking

If your account has a logo configured, the result comes back with the logo composited in the bottom-left corner. Pass useWatermark: false to skip it on a single call. See Watermark for configuration.