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 cotton t-shirt",
"description": "Regular fit crew neck tee, short sleeves, hip length.",
"images": [{ "source": { "url": "https://cdn.example.com/red-tee.jpg" } }]
}],
"person": { "image": { "source": { "id": "<imageId>" } } }
}'
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": "<imageId>" } } }
}'
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", "images": [{ "source": { "fileKey": "product" } }] }],
"person": { "image": { "source": { "fileKey": "person" } } }
}' \
-F "product=@shirt.jpg" \
-F "person=@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": { "url": "https://cdn.example.com/me.jpg" } } },
"externalUserId": "user-123",
"output": { "watermark": false, "aiLabel": true, "keepForDays": 3 }
}'
import { Genlook, ProductNotFoundError } from "@genlook/api";
const client = new Genlook({ apiKey: process.env.GENLOOK_API_KEY! });
const person = { image: { source: { id: imageId } } };
// Send the reference, resend the full product if it expired.
let res;
try {
res = await client.tryOn.create({ products: [{ externalId: "shirt-42" }], person });
} catch (err) {
if (!(err instanceof ProductNotFoundError)) throw err;
res = await client.tryOn.create({
products: [{
externalId: "shirt-42",
title: "Red cotton t-shirt",
description: "Regular fit crew neck tee, short sleeves, hip length.",
images: [{ source: { url: "https://cdn.example.com/red-tee.jpg" } }],
}],
person,
});
}
const result = await client.generations.waitFor(res.generationId);
{
"generationId": "cm8gen456xyz",
"status": "PENDING",
"productExternalId": "shirt-42"
}
{
"code": "PRODUCT_NOT_FOUND",
"message": "Product 'shirt-42' not found.",
"status": 404
}
Try-On
Create Try-On
Start a try-on generation. Costs 1 credit.
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 '{
"products": [{
"externalId": "shirt-42",
"title": "Red cotton t-shirt",
"description": "Regular fit crew neck tee, short sleeves, hip length.",
"images": [{ "source": { "url": "https://cdn.example.com/red-tee.jpg" } }]
}],
"person": { "image": { "source": { "id": "<imageId>" } } }
}'
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": "<imageId>" } } }
}'
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", "images": [{ "source": { "fileKey": "product" } }] }],
"person": { "image": { "source": { "fileKey": "person" } } }
}' \
-F "product=@shirt.jpg" \
-F "person=@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": { "url": "https://cdn.example.com/me.jpg" } } },
"externalUserId": "user-123",
"output": { "watermark": false, "aiLabel": true, "keepForDays": 3 }
}'
import { Genlook, ProductNotFoundError } from "@genlook/api";
const client = new Genlook({ apiKey: process.env.GENLOOK_API_KEY! });
const person = { image: { source: { id: imageId } } };
// Send the reference, resend the full product if it expired.
let res;
try {
res = await client.tryOn.create({ products: [{ externalId: "shirt-42" }], person });
} catch (err) {
if (!(err instanceof ProductNotFoundError)) throw err;
res = await client.tryOn.create({
products: [{
externalId: "shirt-42",
title: "Red cotton t-shirt",
description: "Regular fit crew neck tee, short sleeves, hip length.",
images: [{ source: { url: "https://cdn.example.com/red-tee.jpg" } }],
}],
person,
});
}
const result = await client.generations.waitFor(res.generationId);
{
"generationId": "cm8gen456xyz",
"status": "PENDING",
"productExternalId": "shirt-42"
}
{
"code": "PRODUCT_NOT_FOUND",
"message": "Product 'shirt-42' not found.",
"status": 404
}
Starts a try-on and returns a
All codes: Errors.
generationId. The work runs in the background: poll Generation Status or use client.generations.waitFor(). Costs 1 credit, refunded if the generation fails.
Prefer one call that returns the image? Use Create Try-On (sync): same body, no polling.
Send the full product title and description. They tell the AI what the garment is and how it fits (cut, length),
which gives faster and more accurate results.
Body
array
required
Exactly one item.
Reuse the ID. The first try-on of a product analyzes it, which adds a few seconds. Later calls with just
| You send | Result |
|---|---|
{ externalId } | Uses the existing product. 404 PRODUCT_NOT_FOUND if it expired or never existed. |
{ externalId, title, description, images } | Creates or updates the product. Kept 15 days after last use. |
{ title, description, images } | One-shot product. The response returns a generated productExternalId. Kept 7 days after last use. |
{ externalId } skip that step and return faster. Every try-on resets the product lifetime. See
Products.Show item fields
Show item fields
string
Your product ID. Can’t start with
_anon_.string
Product name. Kept on update when omitted.
string
Product description. Kept on update when omitted.
array
[{ source: { url } }] or [{ source: { fileKey } }] for multipart bytes. Optional classifications next to
source (e.g. { "on_model": "true" }). Replaces the image list on update.integer | null
Lifetime after last use, 1 to 365 days.
null keeps it forever.object
Any JSON, returned on
GET /products/:externalId.object
required
The customer photo:
{ image: { source: { ... } } } with exactly one of:| Source | Use |
|---|---|
id | imageId from Upload Customer Image. Recommended: upload once, reuse, and control the crop. |
url | Public image URL. Downloaded on every call. |
fileKey | Multipart file field in the same request. |
url and fileKey are always cropped to 4:5 around the person.string
Your own user ID, for GDPR deletion. No PII.
object
Show output fields
Show output fields
boolean
Add the EU “AI MODIFIED” badge. Defaults to your account setting. See AI content label.
integer
Image retention:
1, 3 or 7 days. Defaults to your account setting. Ignored when person uses an uploaded id.Testing: a product titled
mock returns the person photo unchanged, fast. It still costs 1 credit.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 cotton t-shirt",
"description": "Regular fit crew neck tee, short sleeves, hip length.",
"images": [{ "source": { "url": "https://cdn.example.com/red-tee.jpg" } }]
}],
"person": { "image": { "source": { "id": "<imageId>" } } }
}'
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": "<imageId>" } } }
}'
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", "images": [{ "source": { "fileKey": "product" } }] }],
"person": { "image": { "source": { "fileKey": "person" } } }
}' \
-F "product=@shirt.jpg" \
-F "person=@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": { "url": "https://cdn.example.com/me.jpg" } } },
"externalUserId": "user-123",
"output": { "watermark": false, "aiLabel": true, "keepForDays": 3 }
}'
import { Genlook, ProductNotFoundError } from "@genlook/api";
const client = new Genlook({ apiKey: process.env.GENLOOK_API_KEY! });
const person = { image: { source: { id: imageId } } };
// Send the reference, resend the full product if it expired.
let res;
try {
res = await client.tryOn.create({ products: [{ externalId: "shirt-42" }], person });
} catch (err) {
if (!(err instanceof ProductNotFoundError)) throw err;
res = await client.tryOn.create({
products: [{
externalId: "shirt-42",
title: "Red cotton t-shirt",
description: "Regular fit crew neck tee, short sleeves, hip length.",
images: [{ source: { url: "https://cdn.example.com/red-tee.jpg" } }],
}],
person,
});
}
const result = await client.generations.waitFor(res.generationId);
Response
string
required
Pass to Generation Status.
string
required
Always
PENDING.string
Your
externalId, or the generated ID of a one-shot product.{
"generationId": "cm8gen456xyz",
"status": "PENDING",
"productExternalId": "shirt-42"
}
{
"code": "PRODUCT_NOT_FOUND",
"message": "Product 'shirt-42' not found.",
"status": 404
}
Errors
| Code | HTTP | Fix |
|---|---|---|
PRODUCT_NOT_FOUND | 404 | Resend the product inline. |
PRODUCT_IMAGES_REQUIRED | 400 | A new or one-shot product needs at least one image. |
CUSTOMER_IMAGE_REQUIRED | 400 | Add person. |
CUSTOMER_IMAGE_FETCH_FAILED | 400 | person URL could not be downloaded. |
MULTIPART_FILE_NOT_FOUND | 400 | A fileKey has no matching file field. |
VALIDATION_FAILED | 400 | See details[]. |
INSUFFICIENT_CREDITS | 402 | Top up. |
RESERVED_EXTERNAL_ID | 409 | externalId can’t start with _anon_. |
Deprecated but still accepted: the 1.0 body with singular
product, customer: { id | url | fileKey },
customerId, useWatermark and retentionDays. Don’t mix it with new fields. See the
Changelog.Was this page helpful?

