Upsert Product (optional)

curl -X POST "https://api.genlook.app/tryon/v1/products" \
  -H "x-api-key: gk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "shirt-42",
    "title": "Red tee",
    "description": "Soft cotton regular fit",
    "images": [
      { "source": { "url": "https://cdn.example/front.jpg" } },
      { "source": { "url": "https://cdn.example/back.jpg" } }
    ]
  }'

curl -X POST "https://api.genlook.app/tryon/v1/products" \
  -H "x-api-key: gk_your_api_key" \
  -F 'data={
        "externalId": "shirt-42",
        "title": "Red tee",
        "description": "Soft cotton regular fit",
        "images": [
          { "source": { "url": "https://cdn.example/front.jpg" } },
          { "source": { "fileKey": "back" } }
        ]
      }' \
  -F "back=@back.jpg"

# Update only the title. Images, description, TTL stay as-is.
curl -X POST "https://api.genlook.app/tryon/v1/products" \
  -H "x-api-key: gk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "shirt-42", "title": "Red tee, restocked" }'

curl -X POST "https://api.genlook.app/tryon/v1/products" \
  -H "x-api-key: gk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "seasonal-001",
    "title": "Summer collection",
    "description": "...",
    "images": [{ "source": { "url": "https://cdn.example/summer.jpg" } }],
    "validForDays": 90
  }'

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

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

// Create or update, keyed on externalId.
const product = await client.products.upsert({
  externalId: "shirt-42",
  title: "Red tee",
  description: "Soft cotton regular fit",
  images: [
    { source: { url: "https://cdn.example.com/front.jpg" } },
    { source: { url: "https://cdn.example.com/back.jpg" } },
  ],
  // validForDays: 90,  // opt into a TTL; omit for lifetime
});

// Multipart with byte uploads:
import { readFile } from "node:fs/promises";
await client.products.upsert({
  externalId: "shirt-42",
  title: "Red tee",
  description: "Soft cotton",
  images: [{ source: { url: "https://cdn.example.com/front.jpg" } }, { source: { fileKey: "back" } }],
  files: {
    back: { data: await readFile("./back.jpg"), mimeType: "image/jpeg" },
  },
});

{
  "externalId": "shirt-42",
  "title": "Red tee",
  "description": "Soft cotton regular fit",
  "metadata": null,
  "validForDays": null,
  "expiresAt": null,
  "lastUsedAt": null,
  "createdAt": "2026-05-13T10:00:00.000Z",
  "updatedAt": "2026-05-13T10:00:00.000Z",
  "images": [
    { "sourceUrl": "https://cdn.example/front.jpg", "order": 0 }
  ]
}

{
  "code": "RESERVED_EXTERNAL_ID",
  "message": "externalId '_anon_foo' is reserved: the '_anon_' prefix is for server-generated IDs.",
  "status": 409
}

{
  "code": "PRODUCT_IMAGES_REQUIRED",
  "message": "Product 'shirt-42' does not exist yet; at least one image is required to create it.",
  "status": 400
}

POST

tryon

products

curl -X POST "https://api.genlook.app/tryon/v1/products" \
  -H "x-api-key: gk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "shirt-42",
    "title": "Red tee",
    "description": "Soft cotton regular fit",
    "images": [
      { "source": { "url": "https://cdn.example/front.jpg" } },
      { "source": { "url": "https://cdn.example/back.jpg" } }
    ]
  }'

curl -X POST "https://api.genlook.app/tryon/v1/products" \
  -H "x-api-key: gk_your_api_key" \
  -F 'data={
        "externalId": "shirt-42",
        "title": "Red tee",
        "description": "Soft cotton regular fit",
        "images": [
          { "source": { "url": "https://cdn.example/front.jpg" } },
          { "source": { "fileKey": "back" } }
        ]
      }' \
  -F "back=@back.jpg"

# Update only the title. Images, description, TTL stay as-is.
curl -X POST "https://api.genlook.app/tryon/v1/products" \
  -H "x-api-key: gk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "shirt-42", "title": "Red tee, restocked" }'

curl -X POST "https://api.genlook.app/tryon/v1/products" \
  -H "x-api-key: gk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "seasonal-001",
    "title": "Summer collection",
    "description": "...",
    "images": [{ "source": { "url": "https://cdn.example/summer.jpg" } }],
    "validForDays": 90
  }'

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

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

// Create or update, keyed on externalId.
const product = await client.products.upsert({
  externalId: "shirt-42",
  title: "Red tee",
  description: "Soft cotton regular fit",
  images: [
    { source: { url: "https://cdn.example.com/front.jpg" } },
    { source: { url: "https://cdn.example.com/back.jpg" } },
  ],
  // validForDays: 90,  // opt into a TTL; omit for lifetime
});

// Multipart with byte uploads:
import { readFile } from "node:fs/promises";
await client.products.upsert({
  externalId: "shirt-42",
  title: "Red tee",
  description: "Soft cotton",
  images: [{ source: { url: "https://cdn.example.com/front.jpg" } }, { source: { fileKey: "back" } }],
  files: {
    back: { data: await readFile("./back.jpg"), mimeType: "image/jpeg" },
  },
});

{
  "externalId": "shirt-42",
  "title": "Red tee",
  "description": "Soft cotton regular fit",
  "metadata": null,
  "validForDays": null,
  "expiresAt": null,
  "lastUsedAt": null,
  "createdAt": "2026-05-13T10:00:00.000Z",
  "updatedAt": "2026-05-13T10:00:00.000Z",
  "images": [
    { "sourceUrl": "https://cdn.example/front.jpg", "order": 0 }
  ]
}

{
  "code": "RESERVED_EXTERNAL_ID",
  "message": "externalId '_anon_foo' is reserved: the '_anon_' prefix is for server-generated IDs.",
  "status": 409
}

{
  "code": "PRODUCT_IMAGES_REQUIRED",
  "message": "Product 'shirt-42' does not exist yet; at least one image is required to create it.",
  "status": 400
}

You probably don’t need this endpoint. The recommended path is the inline product field on POST /try-on: same upsert semantics, one less call. Use this endpoint only when you want:

a lifetime TTL by default (inline upserts default to 15 days),
the product listed in GET /products and visible in the dashboard,
to pre-register a catalog without immediately running a generation.

Creates or updates a product, matched on (account, externalId). The same endpoint handles both: pass full fields the first time, then partial fields to edit later. Products created via this endpoint default to lifetime (no expiry); pass validForDays to opt into a TTL.

Content types

application/json: when all images are URLs.
multipart/form-data: when you ship image bytes inline. The JSON payload arrives in a data form field; each images[].fileKey references a file field by name.

Request

string

required

Your product ID. Reused on subsequent calls to update the same product. Don’t start it with _anon_; that prefix is reserved for IDs we generate.

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

Replaces the full image list on update. Each entry has a source object holding exactly one of:

url: remote URL.
fileKey: name of a multipart file field in the same request.

An optional classifications object can sit 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. Defaults to null (kept forever) when created via this endpoint. Pass a number (1–365) to set a custom lifetime, null to opt back into “kept forever” on an existing product, or omit to preserve the existing value.

object

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

The legacy imageUrls alias from the alpha has been removed. Use images: [{ source: { url } }] instead.

curl -X POST "https://api.genlook.app/tryon/v1/products" \
  -H "x-api-key: gk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "shirt-42",
    "title": "Red tee",
    "description": "Soft cotton regular fit",
    "images": [
      { "source": { "url": "https://cdn.example/front.jpg" } },
      { "source": { "url": "https://cdn.example/back.jpg" } }
    ]
  }'

curl -X POST "https://api.genlook.app/tryon/v1/products" \
  -H "x-api-key: gk_your_api_key" \
  -F 'data={
        "externalId": "shirt-42",
        "title": "Red tee",
        "description": "Soft cotton regular fit",
        "images": [
          { "source": { "url": "https://cdn.example/front.jpg" } },
          { "source": { "fileKey": "back" } }
        ]
      }' \
  -F "back=@back.jpg"

# Update only the title. Images, description, TTL stay as-is.
curl -X POST "https://api.genlook.app/tryon/v1/products" \
  -H "x-api-key: gk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "shirt-42", "title": "Red tee, restocked" }'

curl -X POST "https://api.genlook.app/tryon/v1/products" \
  -H "x-api-key: gk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "seasonal-001",
    "title": "Summer collection",
    "description": "...",
    "images": [{ "source": { "url": "https://cdn.example/summer.jpg" } }],
    "validForDays": 90
  }'

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

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

// Create or update, keyed on externalId.
const product = await client.products.upsert({
  externalId: "shirt-42",
  title: "Red tee",
  description: "Soft cotton regular fit",
  images: [
    { source: { url: "https://cdn.example.com/front.jpg" } },
    { source: { url: "https://cdn.example.com/back.jpg" } },
  ],
  // validForDays: 90,  // opt into a TTL; omit for lifetime
});

// Multipart with byte uploads:
import { readFile } from "node:fs/promises";
await client.products.upsert({
  externalId: "shirt-42",
  title: "Red tee",
  description: "Soft cotton",
  images: [{ source: { url: "https://cdn.example.com/front.jpg" } }, { source: { fileKey: "back" } }],
  files: {
    back: { data: await readFile("./back.jpg"), mimeType: "image/jpeg" },
  },
});

Response

Returns the full product state after the upsert. See List Products for the field-by-field reference.

{
  "externalId": "shirt-42",
  "title": "Red tee",
  "description": "Soft cotton regular fit",
  "metadata": null,
  "validForDays": null,
  "expiresAt": null,
  "lastUsedAt": null,
  "createdAt": "2026-05-13T10:00:00.000Z",
  "updatedAt": "2026-05-13T10:00:00.000Z",
  "images": [
    { "sourceUrl": "https://cdn.example/front.jpg", "order": 0 }
  ]
}

{
  "code": "RESERVED_EXTERNAL_ID",
  "message": "externalId '_anon_foo' is reserved: the '_anon_' prefix is for server-generated IDs.",
  "status": 409
}

{
  "code": "PRODUCT_IMAGES_REQUIRED",
  "message": "Product 'shirt-42' does not exist yet; at least one image is required to create it.",
  "status": 400
}

Get Started

Guides

Try-On

Products (optional)

Account

Releases

Content types

Request

Response

​Content types

​Request

​Response

Content types

Request

Response