Create 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 '{
    "products": [{ "externalId": "shirt-42" }],
    "person": { "image": { "source": { "id": "ephemeral/customer/ttl-7d/.../20260512-….jpeg" } } }
  }'

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 '{
    "products": [{
      "externalId": "shirt-42",
      "title": "Red tee",
      "description": "Soft cotton regular fit",
      "images": [{ "source": { "url": "https://cdn.example/red-tee.jpg" } }]
    }],
    "person": { "image": { "source": { "id": "ephemeral/customer/ttl-7d/.../20260512-….jpeg" } } }
  }'

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 '{
    "products": [{
      "title": "Red tee",
      "description": "Soft cotton regular fit",
      "images": [{ "source": { "url": "https://cdn.example/red-tee.jpg" } }]
    }],
    "person": { "image": { "source": { "id": "ephemeral/customer/ttl-7d/.../20260512-….jpeg" } } }
  }'

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 '{
    "products": [{ "externalId": "shirt-42" }],
    "person": { "image": { "source": { "url": "https://cdn.example/me.jpg" } } }
  }'

curl -X POST "https://api.genlook.app/tryon/v1/try-on" \
  -H "x-api-key: gk_your_api_key" \
  -F 'data={
        "products": [{
          "title": "Red tee",
          "description": "Soft cotton",
          "images": [{ "source": { "fileKey": "primary" } }]
        }],
        "person": { "image": { "source": { "fileKey": "model" } } }
      }' \
  -F "primary=@shirt.jpg" \
  -F "model=@me.jpg"

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 '{
    "products": [{ "externalId": "shirt-42" }],
    "person": { "image": { "source": { "id": "ephemeral/customer/ttl-7d/.../20260512-….jpeg" } } },
    "externalUserId": "your-end-user-id",
    "output": { "watermark": true, "keepForDays": 7 }
  }'

// 1. Upload the person photo
const uploadForm = new FormData();
uploadForm.append("file", personFile);
const { imageId } = await fetch("https://api.genlook.app/tryon/v1/images/upload", {
  method: "POST",
  headers: { "x-api-key": API_KEY },
  body: uploadForm,
}).then((r) => r.json());

// 2. Run the try-on (reference an existing product)
const res = await fetch("https://api.genlook.app/tryon/v1/try-on", {
  method: "POST",
  headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    products: [{ externalId: "shirt-42" }],
    person: { image: { source: { id: imageId } } },
  }),
}).then((r) => r.json());

import { Genlook } from "@genlook/api";

const client = new Genlook({ apiKey: process.env.GENLOOK_API_KEY! });

// Cheapest path: product already exists, person image already uploaded.
const { generationId } = await client.tryOn.create({
  products: [{ externalId: "shirt-42" }],
  person: { image: { source: { id: imageId } } },
});

import { Genlook, ProductNotFoundError } from "@genlook/api";

const client = new Genlook({ apiKey: process.env.GENLOOK_API_KEY! });

// Creates the product on first use, refreshes its TTL on every reuse.
const { generationId } = await client.tryOn.create({
  products: [{
    externalId: "shirt-42",
    title: "Red tee",
    description: "Soft cotton regular fit",
    images: [{ source: { url: "https://cdn.example.com/red-tee.jpg" } }],
  }],
  person: { image: { source: { id: imageId } } },
});

// Ref-first, upsert-on-miss pattern:
try {
  await client.tryOn.create({
    products: [{ externalId: "shirt-42" }],
    person: { image: { source: { id: imageId } } },
  });
} catch (err) {
  if (err instanceof ProductNotFoundError) {
    await client.tryOn.create({
      products: [{
        externalId: "shirt-42",
        title: "Red tee",
        description: "Soft cotton regular fit",
        images: [{ source: { url: "https://cdn.example.com/red-tee.jpg" } }],
      }],
      person: { image: { source: { id: imageId } } },
    });
  } else throw err;
}

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

{
  "generationId": "cm8gen789abc",
  "status": "PENDING",
  "productExternalId": "_anon_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}

{
  "code": "INSUFFICIENT_CREDITS",
  "message": "Insufficient credits. Top up the account balance and retry.",
  "status": 402
}

{
  "code": "PRODUCT_NOT_FOUND",
  "message": "Product 'shirt-42' not found.",
  "status": 404
}

POST

tryon

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 '{
    "products": [{ "externalId": "shirt-42" }],
    "person": { "image": { "source": { "id": "ephemeral/customer/ttl-7d/.../20260512-….jpeg" } } }
  }'

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 '{
    "products": [{
      "externalId": "shirt-42",
      "title": "Red tee",
      "description": "Soft cotton regular fit",
      "images": [{ "source": { "url": "https://cdn.example/red-tee.jpg" } }]
    }],
    "person": { "image": { "source": { "id": "ephemeral/customer/ttl-7d/.../20260512-….jpeg" } } }
  }'

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 '{
    "products": [{
      "title": "Red tee",
      "description": "Soft cotton regular fit",
      "images": [{ "source": { "url": "https://cdn.example/red-tee.jpg" } }]
    }],
    "person": { "image": { "source": { "id": "ephemeral/customer/ttl-7d/.../20260512-….jpeg" } } }
  }'

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 '{
    "products": [{ "externalId": "shirt-42" }],
    "person": { "image": { "source": { "url": "https://cdn.example/me.jpg" } } }
  }'

curl -X POST "https://api.genlook.app/tryon/v1/try-on" \
  -H "x-api-key: gk_your_api_key" \
  -F 'data={
        "products": [{
          "title": "Red tee",
          "description": "Soft cotton",
          "images": [{ "source": { "fileKey": "primary" } }]
        }],
        "person": { "image": { "source": { "fileKey": "model" } } }
      }' \
  -F "primary=@shirt.jpg" \
  -F "model=@me.jpg"

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 '{
    "products": [{ "externalId": "shirt-42" }],
    "person": { "image": { "source": { "id": "ephemeral/customer/ttl-7d/.../20260512-….jpeg" } } },
    "externalUserId": "your-end-user-id",
    "output": { "watermark": true, "keepForDays": 7 }
  }'

// 1. Upload the person photo
const uploadForm = new FormData();
uploadForm.append("file", personFile);
const { imageId } = await fetch("https://api.genlook.app/tryon/v1/images/upload", {
  method: "POST",
  headers: { "x-api-key": API_KEY },
  body: uploadForm,
}).then((r) => r.json());

// 2. Run the try-on (reference an existing product)
const res = await fetch("https://api.genlook.app/tryon/v1/try-on", {
  method: "POST",
  headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    products: [{ externalId: "shirt-42" }],
    person: { image: { source: { id: imageId } } },
  }),
}).then((r) => r.json());

import { Genlook } from "@genlook/api";

const client = new Genlook({ apiKey: process.env.GENLOOK_API_KEY! });

// Cheapest path: product already exists, person image already uploaded.
const { generationId } = await client.tryOn.create({
  products: [{ externalId: "shirt-42" }],
  person: { image: { source: { id: imageId } } },
});

import { Genlook, ProductNotFoundError } from "@genlook/api";

const client = new Genlook({ apiKey: process.env.GENLOOK_API_KEY! });

// Creates the product on first use, refreshes its TTL on every reuse.
const { generationId } = await client.tryOn.create({
  products: [{
    externalId: "shirt-42",
    title: "Red tee",
    description: "Soft cotton regular fit",
    images: [{ source: { url: "https://cdn.example.com/red-tee.jpg" } }],
  }],
  person: { image: { source: { id: imageId } } },
});

// Ref-first, upsert-on-miss pattern:
try {
  await client.tryOn.create({
    products: [{ externalId: "shirt-42" }],
    person: { image: { source: { id: imageId } } },
  });
} catch (err) {
  if (err instanceof ProductNotFoundError) {
    await client.tryOn.create({
      products: [{
        externalId: "shirt-42",
        title: "Red tee",
        description: "Soft cotton regular fit",
        images: [{ source: { url: "https://cdn.example.com/red-tee.jpg" } }],
      }],
      person: { image: { source: { id: imageId } } },
    });
  } else throw err;
}

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

{
  "generationId": "cm8gen789abc",
  "status": "PENDING",
  "productExternalId": "_anon_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}

{
  "code": "INSUFFICIENT_CREDITS",
  "message": "Insufficient credits. Top up the account balance and retry.",
  "status": 402
}

{
  "code": "PRODUCT_NOT_FOUND",
  "message": "Product 'shirt-42' not found.",
  "status": 404
}

Creates a virtual try-on generation. Runs asynchronously; poll Generation Status for the result. Each generation consumes 1 credit. The body has three parts: a products array describing what to try on, a person image (the shopper photo, either pre-uploaded or shipped inline), and optional externalUserId / output controls.

To test your integration without waiting on AI output, send a product whose title is mock (case-insensitive). The generation runs through the whole pipeline but returns the person image unchanged, so responses are fast and deterministic. Mock generations still consume 1 credit.

Products

products is an array. For now it must hold exactly one item (multi-product try-on is on the roadmap). Each item 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.

array

required

Array of product specs to try on. Exactly one item for now (multi-product try-on is on the roadmap).

Show product item fields

string

Your product ID. Omit for one-shot generations.

string

Optional. Helps the AI classify the product category more accurately. Preserved on updates if omitted.

string

Optional. Helps the AI classify the product category more accurately. Preserved on updates if omitted.

array

One or more image entries. Each entry has a source object holding exactly one of url (remote URL) or fileKey (name of a multipart file field in the same request), plus an optional classifications object alongside source.

The old flat shape ({ url } / { fileKey, classifications } with the fields at the top level) is still accepted but deprecated. Prefer { source: { url | fileKey }, classifications? }.

integer | null

How long the product lives between uses, in days. Pass a number (1–365) to set a custom lifetime; pass null to keep it forever; omit to use the default. Updates preserve the existing value when omitted.

object

Free-form JSON returned with the product on GET /products/:externalId.

Person

The shopper photo. person.image.source holds exactly one of id, url, or fileKey.

object

required

Show person fields

object

required

Show image fields

object

required

Exactly one of id, url, or fileKey.

Show source fields

string

Image id from a prior POST /images/upload. Recommended: decouples the upload from the generation so you can retry without re-uploading, and is the only path that controls cropping (set crop=false on upload).

string

Remote URL. The server downloads on every call. Always 4:5-cropped.

string

Name of a multipart file field in the same request. Always 4:5-cropped.

string

Optional opaque identifier of your own end user (e.g. your user ID). No PII. It’s used purely as an attribution and GDPR key. When set, the generation (and the person image uploaded as part of this call) can be wiped on demand via DELETE /customers/:customerId (pass the same value as the path segment).

object

Optional controls over the generated result.

Show output fields

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.

boolean

default:"true"

Composite the EU “AI MODIFIED” label onto the result. Defaults to your account setting. Results always carry machine-readable AI-provenance metadata, whatever this is set to. See AI content label.

integer

How long the generation’s stored images are kept. One of 1, 3, 7. Defaults to your account’s configured retention window. Ignored when person.image.source.id references an already-uploaded image (the existing storage path is reused).

The previous request shape is still accepted but deprecated (this is not a breaking change). The old form used a top-level singular product object, a customer object (customer: { source: { id | url | fileKey } }), a top-level customerId, and top-level useWatermark / retentionDays. Migrate to products: [...], person.image.source, externalUserId, and output.watermark / output.keepForDays. See the Changelog.

Recommended flow

Upload the person image once via POST /images/upload, which gets you an imageId you can reuse.
Call /try-on with { products: [{ externalId }], person: { image: { source: { id: imageId } } } } for repeat generations against known products, or with a full inline product when introducing a new SKU.

The inline person.image.source.url and person.image.source.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 '{
    "products": [{ "externalId": "shirt-42" }],
    "person": { "image": { "source": { "id": "ephemeral/customer/ttl-7d/.../20260512-….jpeg" } } }
  }'

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 '{
    "products": [{
      "externalId": "shirt-42",
      "title": "Red tee",
      "description": "Soft cotton regular fit",
      "images": [{ "source": { "url": "https://cdn.example/red-tee.jpg" } }]
    }],
    "person": { "image": { "source": { "id": "ephemeral/customer/ttl-7d/.../20260512-….jpeg" } } }
  }'

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 '{
    "products": [{
      "title": "Red tee",
      "description": "Soft cotton regular fit",
      "images": [{ "source": { "url": "https://cdn.example/red-tee.jpg" } }]
    }],
    "person": { "image": { "source": { "id": "ephemeral/customer/ttl-7d/.../20260512-….jpeg" } } }
  }'

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 '{
    "products": [{ "externalId": "shirt-42" }],
    "person": { "image": { "source": { "url": "https://cdn.example/me.jpg" } } }
  }'

curl -X POST "https://api.genlook.app/tryon/v1/try-on" \
  -H "x-api-key: gk_your_api_key" \
  -F 'data={
        "products": [{
          "title": "Red tee",
          "description": "Soft cotton",
          "images": [{ "source": { "fileKey": "primary" } }]
        }],
        "person": { "image": { "source": { "fileKey": "model" } } }
      }' \
  -F "primary=@shirt.jpg" \
  -F "model=@me.jpg"

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 '{
    "products": [{ "externalId": "shirt-42" }],
    "person": { "image": { "source": { "id": "ephemeral/customer/ttl-7d/.../20260512-….jpeg" } } },
    "externalUserId": "your-end-user-id",
    "output": { "watermark": true, "keepForDays": 7 }
  }'

// 1. Upload the person photo
const uploadForm = new FormData();
uploadForm.append("file", personFile);
const { imageId } = await fetch("https://api.genlook.app/tryon/v1/images/upload", {
  method: "POST",
  headers: { "x-api-key": API_KEY },
  body: uploadForm,
}).then((r) => r.json());

// 2. Run the try-on (reference an existing product)
const res = await fetch("https://api.genlook.app/tryon/v1/try-on", {
  method: "POST",
  headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    products: [{ externalId: "shirt-42" }],
    person: { image: { source: { id: imageId } } },
  }),
}).then((r) => r.json());

import { Genlook } from "@genlook/api";

const client = new Genlook({ apiKey: process.env.GENLOOK_API_KEY! });

// Cheapest path: product already exists, person image already uploaded.
const { generationId } = await client.tryOn.create({
  products: [{ externalId: "shirt-42" }],
  person: { image: { source: { id: imageId } } },
});

import { Genlook, ProductNotFoundError } from "@genlook/api";

const client = new Genlook({ apiKey: process.env.GENLOOK_API_KEY! });

// Creates the product on first use, refreshes its TTL on every reuse.
const { generationId } = await client.tryOn.create({
  products: [{
    externalId: "shirt-42",
    title: "Red tee",
    description: "Soft cotton regular fit",
    images: [{ source: { url: "https://cdn.example.com/red-tee.jpg" } }],
  }],
  person: { image: { source: { id: imageId } } },
});

// Ref-first, upsert-on-miss pattern:
try {
  await client.tryOn.create({
    products: [{ externalId: "shirt-42" }],
    person: { image: { source: { id: imageId } } },
  });
} catch (err) {
  if (err instanceof ProductNotFoundError) {
    await client.tryOn.create({
      products: [{
        externalId: "shirt-42",
        title: "Red tee",
        description: "Soft cotton regular fit",
        images: [{ source: { url: "https://cdn.example.com/red-tee.jpg" } }],
      }],
      person: { image: { source: { id: imageId } } },
    });
  } else throw err;
}

Response

string

required

Poll GET /generations/:id every 2s until status is COMPLETED or FAILED.

string

required

Initial status: PENDING.

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"
}

{
  "generationId": "cm8gen789abc",
  "status": "PENDING",
  "productExternalId": "_anon_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}

{
  "code": "INSUFFICIENT_CREDITS",
  "message": "Insufficient credits. Top up the account balance and retry.",
  "status": 402
}

{
  "code": "PRODUCT_NOT_FOUND",
  "message": "Product 'shirt-42' not found.",
  "status": 404
}

Errors

Code	HTTP	Meaning
`PRODUCT_NOT_FOUND`	404	The referenced `externalId` doesn’t exist (or has expired). Retry with a full inline payload.
`PRODUCT_IMAGES_REQUIRED`	400	One-shot call (no `externalId`) without any image.
`CUSTOMER_IMAGE_REQUIRED`	400	`person` is missing.
`CUSTOMER_IMAGE_FETCH_FAILED`	400	`person.image.source.url` could not be downloaded (DNS fail, host unreachable, or non-2xx status).
`MULTIPART_FILE_NOT_FOUND`	400	A `fileKey` from `data` doesn’t appear in the multipart payload.
`VALIDATION_FAILED`	400	Request body failed validation; see `details[]` for the offending fields.
`INSUFFICIENT_CREDITS`	402	Account is out of credits.
`RESERVED_EXTERNAL_ID`	409	`product.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 output: { watermark: false } to skip it on a single call. See Watermark for configuration.

Get Started

Guides

Try-On

Products (optional)

Account

Releases

Products

Person

Recommended flow

Examples

Response

Errors

Watermarking

​Products

​Person

​Recommended flow

​Examples

​Response

​Errors

​Watermarking

Products

Person

Recommended flow

Examples

Response

Errors

Watermarking