{"openapi":"3.1.0","paths":{"/tryon/v1/products":{"post":{"operationId":"upsertProduct","tags":["Products"],"summary":"Create or update a product","description":"Create-or-update (upsert) keyed on your own `externalId`: the product is created when the ID is new and replaced when it exists. Optional: a try-on can also carry its product inline. JSON when images are URLs, multipart (`data` plus image files) to upload bytes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProductSpec"}]},"example":{"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-front.jpg"}}]}}}},"responses":{"201":{"description":"The product as stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"The request is invalid. `code` says why; `VALIDATION_FAILED` lists the fields in `details`.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"VALIDATION_FAILED","message":"Request body failed validation. See `details` for per-field errors.","status":400,"details":[{"path":"products.0.images.0.source.url","message":"Required"}]}}}},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"409":{"description":"Conflict: a reserved `externalId`, or the first request with this `Idempotency-Key` is still running (retry after `Retry-After`).","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"IDEMPOTENCY_IN_PROGRESS","message":"The first request sent with this Idempotency-Key is still running. Retry shortly.","status":409,"details":{"retryAfter":5}}}}},"413":{"description":"An uploaded file is over 10 MB.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"FILE_TOO_LARGE","message":"File exceeds the 10 MB limit.","status":413}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}}},"security":[{"x-api-key":[]}]},"get":{"operationId":"listProducts","tags":["Products"],"summary":"List products","description":"The products of the account, one page at a time. Follow `nextCursor` while `hasMore` is true.","parameters":[{"name":"limit","required":false,"in":"query","schema":{"type":"string"},"description":"Products per page."},{"name":"cursor","required":false,"in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous page (`nextCursor`). Omit for the first page."}],"responses":{"200":{"description":"One page of products.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductList"}}}},"400":{"description":"The request is invalid. `code` says why; `VALIDATION_FAILED` lists the fields in `details`.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"VALIDATION_FAILED","message":"Request body failed validation. See `details` for per-field errors.","status":400,"details":[{"path":"products.0.images.0.source.url","message":"Required"}]}}}},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}}},"security":[{"x-api-key":[]}]}},"/tryon/v1/products/{externalId}":{"get":{"operationId":"getProduct","tags":["Products"],"summary":"Get a product","description":"One product, by the `externalId` you gave it.","parameters":[{"name":"externalId","required":true,"in":"path","schema":{"type":"string"},"description":"Your ID of the product."}],"responses":{"200":{"description":"The product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"404":{"description":"The resource does not exist on this account.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"PRODUCT_NOT_FOUND","message":"Product 'shirt-42' not found.","status":404}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}}},"security":[{"x-api-key":[]}]},"delete":{"operationId":"deleteProduct","tags":["Products"],"summary":"Delete a product","description":"Deletes the product and its stored images. Past generations are kept. This cannot be undone; create the product again to restore it.","parameters":[{"name":"externalId","required":true,"in":"path","schema":{"type":"string"},"description":"Your ID of the product."}],"responses":{"204":{"description":"Deleted."},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"404":{"description":"The resource does not exist on this account.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"PRODUCT_NOT_FOUND","message":"Product 'shirt-42' not found.","status":404}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}}},"security":[{"x-api-key":[]}]}},"/tryon/v1/products/{externalId}/stats":{"get":{"operationId":"getProductStats","tags":["Products"],"summary":"Get the try-on statistics of a product","description":"How many try-ons ran on the product, by outcome, and their average duration. Lifetime unless `from` and `to` narrow it.","parameters":[{"name":"externalId","required":true,"in":"path","schema":{"type":"string"},"description":"Your ID of the product."},{"name":"from","required":false,"in":"query","schema":{"type":"string"},"description":"Start of the window, ISO 8601."},{"name":"to","required":false,"in":"query","schema":{"type":"string"},"description":"End of the window, ISO 8601."}],"responses":{"200":{"description":"The statistics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductStats"},"example":{"totalGenerations":120,"completedGenerations":117,"failedGenerations":3,"avgGenerationTimeMs":8200}}}},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"404":{"description":"The resource does not exist on this account.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"PRODUCT_NOT_FOUND","message":"Product 'shirt-42' not found.","status":404}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}}},"security":[{"x-api-key":[]}]}},"/tryon/v1/images/upload":{"post":{"operationId":"uploadImage","tags":["Try-On"],"summary":"Upload a person photo","description":"Uploads a photo of a person (multipart `file`, 10 MB at most) and returns an `imageId` to reuse in try-ons. The photo is cropped to 4:5 around the person unless `crop` is false, and deleted after its retention period. Free.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/UploadImageBody"}]},{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The photo: JPEG, PNG, WebP or HEIC, 10 MB at most."}}}]}}}},"responses":{"201":{"description":"The photo is stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadImageResponse"},"example":{"imageId":"customers/acc_123/2026-09-30/abc.jpg","imageUrl":"https://storage.googleapis.com/..."}}}},"400":{"description":"The request is invalid. `code` says why; `VALIDATION_FAILED` lists the fields in `details`.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"VALIDATION_FAILED","message":"Request body failed validation. See `details` for per-field errors.","status":400,"details":[{"path":"products.0.images.0.source.url","message":"Required"}]}}}},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"413":{"description":"An uploaded file is over 10 MB.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"FILE_TOO_LARGE","message":"File exceeds the 10 MB limit.","status":413}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}}},"security":[{"x-api-key":[]}]}},"/tryon/v1/try-on":{"post":{"operationId":"createTryOn","tags":["Try-On"],"summary":"Create a try-on","description":"Starts a try-on of one to four products on a person photo and returns its `generationId` right away. Read the result with `GET /generations/{id}` (about 10 seconds) or receive the `generation.completed` webhook. Costs 1 credit (2 for several products, 1 more at 2K), refunded when the generation fails. `mock: true` simulates the call: free, no AI, a fixed result image, for testing an integration. Send an `Idempotency-Key` to retry safely without creating or paying for a second try-on. At most 20 try-ons run at once per account; use batches for bulk work.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenerateTryOn"}]},"example":{"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-front.jpg"}}]}],"person":{"image":{"source":{"url":"https://cdn.example.com/shopper.jpg"}}}}}}},"responses":{"201":{"description":"The try-on is queued.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateTryOnResponse"},"example":{"generationId":"cm8gen456xyz","status":"PENDING","productExternalId":"shirt-42","productExternalIds":["shirt-42"]}}}},"400":{"description":"The request is invalid. `code` says why; `VALIDATION_FAILED` lists the fields in `details`.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"VALIDATION_FAILED","message":"Request body failed validation. See `details` for per-field errors.","status":400,"details":[{"path":"products.0.images.0.source.url","message":"Required"}]}}}},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"402":{"description":"Not enough credits, or the API key reached its monthly credit limit. Nothing was charged.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INSUFFICIENT_CREDITS","message":"Insufficient credits. Top up the account balance and retry.","status":402}}}},"403":{"description":"The resource belongs to another account, or the account may not use this endpoint.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"FORBIDDEN","message":"Forbidden. The requested resource does not belong to this account.","status":403}}}},"404":{"description":"The resource does not exist on this account.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"PRODUCT_NOT_FOUND","message":"Product 'shirt-42' not found.","status":404}}}},"409":{"description":"Conflict: a reserved `externalId`, or the first request with this `Idempotency-Key` is still running (retry after `Retry-After`).","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"IDEMPOTENCY_IN_PROGRESS","message":"The first request sent with this Idempotency-Key is still running. Retry shortly.","status":409,"details":{"retryAfter":5}}}}},"413":{"description":"An uploaded file is over 10 MB.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"FILE_TOO_LARGE","message":"File exceeds the 10 MB limit.","status":413}}}},"422":{"description":"The request is well formed but cannot be run: an `Idempotency-Key` reused with another body, or a product the endpoint does not support.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"IDEMPOTENCY_KEY_REUSED","message":"This Idempotency-Key was already used with a different request. Use a new key for a new request.","status":422}}}},"429":{"description":"More than 20 try-ons are running on the account. Wait for `Retry-After` seconds and retry. Nothing was charged.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"RATE_LIMITED","message":"Too many try-ons running at once for this account (limit 20). Wait for some to finish, or send bulk work through the batch endpoint (POST /tryon/v1/batches).","status":429,"details":{"reason":"CONCURRENCY_LIMIT","limit":20,"retryAfter":10}}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}}},"security":[{"x-api-key":[]}]}},"/tryon/v1/try-on/sync":{"post":{"operationId":"createTryOnSync","tags":["Try-On"],"summary":"Create a try-on and wait for the result","description":"Same body and price as `POST /try-on`, but the request stays open until the result is ready, for up to 90 seconds. Returns 200 with `resultImageUrl`, or 202 with the `generationId` to poll when it is still running. A failed generation comes back as its error (the credit is refunded). With an `Idempotency-Key`, a retry waits on the same generation instead of starting another.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenerateTryOn"}]},"example":{"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-front.jpg"}}]}],"person":{"image":{"source":{"url":"https://cdn.example.com/shopper.jpg"}}}}}}},"responses":{"200":{"description":"The result is ready.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncTryOnResponse"},"example":{"generationId":"cm8gen456xyz","status":"COMPLETED","resultImageUrl":"https://storage.googleapis.com/...","createdAt":"2026-09-30T10:00:00.000Z","updatedAt":"2026-09-30T10:00:09.800Z","productExternalIds":["shirt-42"]}}}},"202":{"description":"Still running after 90 seconds. Poll `GET /generations/{id}`.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncTryOnResponse"},"example":{"generationId":"cm8gen456xyz","status":"PROCESSING","productExternalIds":["shirt-42"],"createdAt":"2026-09-30T10:00:00.000Z","updatedAt":"2026-09-30T10:01:30.000Z"}}}},"400":{"description":"The request is invalid. `code` says why; `VALIDATION_FAILED` lists the fields in `details`.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"VALIDATION_FAILED","message":"Request body failed validation. See `details` for per-field errors.","status":400,"details":[{"path":"products.0.images.0.source.url","message":"Required"}]}}}},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"402":{"description":"Not enough credits, or the API key reached its monthly credit limit. Nothing was charged.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INSUFFICIENT_CREDITS","message":"Insufficient credits. Top up the account balance and retry.","status":402}}}},"403":{"description":"The resource belongs to another account, or the account may not use this endpoint.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"FORBIDDEN","message":"Forbidden. The requested resource does not belong to this account.","status":403}}}},"404":{"description":"The resource does not exist on this account.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"PRODUCT_NOT_FOUND","message":"Product 'shirt-42' not found.","status":404}}}},"409":{"description":"Conflict: a reserved `externalId`, or the first request with this `Idempotency-Key` is still running (retry after `Retry-After`).","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"IDEMPOTENCY_IN_PROGRESS","message":"The first request sent with this Idempotency-Key is still running. Retry shortly.","status":409,"details":{"retryAfter":5}}}}},"413":{"description":"An uploaded file is over 10 MB.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"FILE_TOO_LARGE","message":"File exceeds the 10 MB limit.","status":413}}}},"422":{"description":"The request is well formed but cannot be run: an `Idempotency-Key` reused with another body, or a product the endpoint does not support.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"IDEMPOTENCY_KEY_REUSED","message":"This Idempotency-Key was already used with a different request. Use a new key for a new request.","status":422}}}},"429":{"description":"More than 20 try-ons are running on the account. Wait for `Retry-After` seconds and retry. Nothing was charged.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"RATE_LIMITED","message":"Too many try-ons running at once for this account (limit 20). Wait for some to finish, or send bulk work through the batch endpoint (POST /tryon/v1/batches).","status":429,"details":{"reason":"CONCURRENCY_LIMIT","limit":20,"retryAfter":10}}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}},"504":{"description":"The generation passed its 60 second deadline and was cancelled. The credit is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"GENERATION_TIMEOUT","message":"The try-on generation did not finish within 60 seconds and was cancelled. The credit has been refunded; please retry.","status":504,"details":{"generationId":"cm8gen456xyz"}}}}}},"security":[{"x-api-key":[]}]}},"/tryon/v1/generations/{id}":{"get":{"operationId":"getGeneration","tags":["Try-On"],"summary":"Get a try-on result","description":"Status of a generation: `PENDING`, `PROCESSING`, `COMPLETED` (with `resultImageUrl`) or `FAILED` (with `errorCode`). Poll every second or two until it is `COMPLETED` or `FAILED`.","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"},"description":"The `generationId` returned when the try-on was created."}],"responses":{"200":{"description":"The generation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationStatusResponse"},"example":{"generationId":"cm8gen456xyz","status":"COMPLETED","resultImageUrl":"https://storage.googleapis.com/...","createdAt":"2026-09-30T10:00:00.000Z","updatedAt":"2026-09-30T10:00:09.800Z"}}}},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"404":{"description":"The resource does not exist on this account.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"PRODUCT_NOT_FOUND","message":"Product 'shirt-42' not found.","status":404}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}}},"security":[{"x-api-key":[]}]}},"/tryon/v1/customers/{customerId}":{"delete":{"operationId":"deleteCustomerData","tags":["Account"],"summary":"Delete a shopper's data","description":"Deletes every photo and result stored for the `externalUserId` you sent with uploads and try-ons, and detaches their generations from that ID. For GDPR erasure requests. This cannot be undone. An unknown ID also returns 204.","parameters":[{"name":"customerId","required":true,"in":"path","schema":{"type":"string"},"description":"The `externalUserId` of the shopper."}],"responses":{"204":{"description":"Deleted, or nothing to delete."},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}}},"security":[{"x-api-key":[]}]}},"/tryon/v1/account/credits":{"get":{"operationId":"getCredits","tags":["Account"],"summary":"Get the credit balance","description":"Credits left on the account. A try-on costs 1 credit, 2 for several products, 1 more at 2K.","responses":{"200":{"description":"The balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credits"},"example":{"creditBalance":942}}}},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}}},"security":[{"x-api-key":[]}]}},"/tryon/v1/usage":{"get":{"operationId":"listUsage","tags":["Account"],"summary":"List the credits charged per generation","description":"One row per generation with the credits it was charged, oldest first, to reconcile with your own logs and invoice. Follow `nextCursor` while `hasMore` is true.","parameters":[{"name":"from","required":false,"in":"query","description":"Only generations created at or after this ISO 8601 time.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Only generations created at or after this ISO 8601 timestamp."}},{"name":"to","required":false,"in":"query","description":"Only generations created before this ISO 8601 time.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Only generations created before this ISO 8601 timestamp."}},{"name":"limit","required":false,"in":"query","description":"Rows per page, up to 1000. Default 100.","schema":{"type":"integer","minimum":1,"maximum":1000,"description":"Page size, 1 to 1000. Ignored by the CSV export."}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from the previous page (`nextCursor`). Omit for the first page.","schema":{"type":"string","minLength":1,"maxLength":128,"description":"`nextCursor` of the previous page. Ignored by the CSV export."}}],"responses":{"200":{"description":"One page of usage rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageList"}}}},"400":{"description":"The request is invalid. `code` says why; `VALIDATION_FAILED` lists the fields in `details`.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"VALIDATION_FAILED","message":"Request body failed validation. See `details` for per-field errors.","status":400,"details":[{"path":"products.0.images.0.source.url","message":"Required"}]}}}},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}}},"security":[{"x-api-key":[]}]}},"/tryon/v1/usage/export":{"get":{"operationId":"exportUsage","tags":["Account"],"summary":"Export usage as CSV","description":"The rows of `GET /usage` for the whole window, as one CSV file.","parameters":[{"name":"from","required":false,"in":"query","description":"Only generations created at or after this ISO 8601 time.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Only generations created at or after this ISO 8601 timestamp."}},{"name":"to","required":false,"in":"query","description":"Only generations created before this ISO 8601 time.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Only generations created before this ISO 8601 timestamp."}},{"name":"limit","required":false,"in":"query","description":"Ignored: the export returns the whole window.","schema":{"type":"integer","minimum":1,"maximum":1000,"description":"Page size, 1 to 1000. Ignored by the CSV export."}},{"name":"cursor","required":false,"in":"query","description":"Ignored: the export returns the whole window.","schema":{"type":"string","minLength":1,"maxLength":128,"description":"`nextCursor` of the previous page. Ignored by the CSV export."}}],"responses":{"200":{"description":"The CSV file.","content":{"text/csv":{"schema":{"type":"string"},"example":"generation_id,created_at,completed_at,status,credits,batch_id,api_key_id\n"}}},"400":{"description":"The request is invalid. `code` says why; `VALIDATION_FAILED` lists the fields in `details`.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"VALIDATION_FAILED","message":"Request body failed validation. See `details` for per-field errors.","status":400,"details":[{"path":"products.0.images.0.source.url","message":"Required"}]}}}},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}}},"security":[{"x-api-key":[]}]}},"/tryon/v1/batches":{"post":{"operationId":"createBatch","tags":["Batches"],"summary":"Create a batch of try-ons","description":"Submits 1 to 500 try-ons that run on spare capacity within 4 hours, at half price. Paid accounts only. Half a credit per item is held now; only completed items are charged when the batch is done. Undo it with `POST /batches/{batchId}/cancel` at any time before the items start. Send an `Idempotency-Key` to retry safely without submitting the batch twice.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBatch"},"example":{"items":[{"customId":"order-1001","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-front.jpg"}}]}],"person":{"image":{"source":{"url":"https://cdn.example.com/shopper.jpg"}}}}]}}}},"responses":{"202":{"description":"The batch is accepted.","headers":{"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"},"example":{"batchId":"cm8batch123","status":"RUNNING","itemCount":1,"completedCount":0,"failedCount":0,"reservedCredits":1,"chargedCredits":null,"createdAt":"2026-09-30T10:00:00.000Z","expiresAt":"2026-09-30T14:00:00.000Z","items":[{"customId":"order-1001","generationId":"cm8gen456xyz","status":"PENDING"}],"nextCursor":null}}}},"400":{"description":"The request is invalid. `code` says why; `VALIDATION_FAILED` lists the fields in `details`.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"VALIDATION_FAILED","message":"Request body failed validation. See `details` for per-field errors.","status":400,"details":[{"path":"products.0.images.0.source.url","message":"Required"}]}}}},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"402":{"description":"Not enough credits, or the API key reached its monthly credit limit. Nothing was charged.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INSUFFICIENT_CREDITS","message":"Insufficient credits. Top up the account balance and retry.","status":402}}}},"403":{"description":"The resource belongs to another account, or the account may not use this endpoint.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"FORBIDDEN","message":"Forbidden. The requested resource does not belong to this account.","status":403}}}},"409":{"description":"Conflict: a reserved `externalId`, or the first request with this `Idempotency-Key` is still running (retry after `Retry-After`).","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"IDEMPOTENCY_IN_PROGRESS","message":"The first request sent with this Idempotency-Key is still running. Retry shortly.","status":409,"details":{"retryAfter":5}}}}},"422":{"description":"The request is well formed but cannot be run: an `Idempotency-Key` reused with another body, or a product the endpoint does not support.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"IDEMPOTENCY_KEY_REUSED","message":"This Idempotency-Key was already used with a different request. Use a new key for a new request.","status":422}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}}},"security":[{"x-api-key":[]}]}},"/tryon/v1/batches/{batchId}":{"get":{"operationId":"getBatch","tags":["Batches"],"summary":"Get a batch and its items","description":"The batch with its counts and one page of its items, in submit order. Each completed item carries its `resultImageUrl`.","parameters":[{"name":"batchId","required":true,"in":"path","schema":{"type":"string"},"description":"The `batchId` returned when the batch was created."},{"name":"cursor","required":false,"in":"query","schema":{"type":"string","minLength":1},"description":"Opaque cursor from the previous page (`nextCursor`). Omit for the first page."},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":500},"description":"Items per page, 1 to 500. Default 100."}],"responses":{"200":{"description":"The batch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"},"example":{"batchId":"cm8batch123","status":"RUNNING","itemCount":1,"completedCount":0,"failedCount":0,"reservedCredits":1,"chargedCredits":null,"createdAt":"2026-09-30T10:00:00.000Z","expiresAt":"2026-09-30T14:00:00.000Z","items":[{"customId":"order-1001","generationId":"cm8gen456xyz","status":"PENDING"}],"nextCursor":null}}}},"400":{"description":"The request is invalid. `code` says why; `VALIDATION_FAILED` lists the fields in `details`.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"VALIDATION_FAILED","message":"Request body failed validation. See `details` for per-field errors.","status":400,"details":[{"path":"products.0.images.0.source.url","message":"Required"}]}}}},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"404":{"description":"The resource does not exist on this account.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"PRODUCT_NOT_FOUND","message":"Product 'shirt-42' not found.","status":404}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}}},"security":[{"x-api-key":[]}]}},"/tryon/v1/batches/{batchId}/cancel":{"post":{"operationId":"cancelBatch","tags":["Batches"],"summary":"Cancel a batch","description":"Cancels a batch. Items that have not started fail with `BATCH_CANCELLED` and are not charged; an item already running finishes and is charged. Possible at any time within the 4 hours the batch has to run. Calling it again, or on a finished batch, changes nothing and returns the batch.","parameters":[{"name":"batchId","required":true,"in":"path","schema":{"type":"string"},"description":"The batch to cancel."}],"responses":{"200":{"description":"The batch after cancellation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"},"example":{"batchId":"cm8batch123","status":"CANCELLED","itemCount":1,"completedCount":0,"failedCount":0,"reservedCredits":1,"chargedCredits":null,"createdAt":"2026-09-30T10:00:00.000Z","expiresAt":"2026-09-30T14:00:00.000Z","items":[{"customId":"order-1001","generationId":"cm8gen456xyz","status":"PENDING"}],"nextCursor":null}}}},"401":{"description":"The API key is missing, invalid or inactive.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"MISSING_API_KEY","message":"Missing 'x-api-key' header.","status":401}}}},"404":{"description":"The resource does not exist on this account.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"PRODUCT_NOT_FOUND","message":"Product 'shirt-42' not found.","status":404}}}},"500":{"description":"Unexpected server error. Safe to retry; any credit debited is refunded.","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected error occurred. Please retry or contact support.","status":500}}}}},"security":[{"x-api-key":[]}]}}},"info":{"title":"Genlook Virtual Try-On API","version":"1.12.0","summary":"Generative AI virtual try-on from one person photo and standard product images.","description":"Send a photo of a person and the images of a product, get back a photo of that person wearing the product. Every endpoint is authenticated with the `x-api-key` header. Errors share one shape; branch on `code`. Creating calls accept an `Idempotency-Key` header and are then safe to retry. Narrative docs: https://genlook.app/docs/tryon-api","termsOfService":"https://genlook.app/terms","contact":{"name":"Genlook support","url":"https://genlook.app/docs/tryon-api","email":"support@genlook.app"}},"tags":[{"name":"Try-On","description":"Upload a person photo, run a try-on, read its result."},{"name":"Batches","description":"Many try-ons at half price, run within 4 hours. Paid accounts only."},{"name":"Products","description":"Optional product catalogue, so try-ons can reference a product by its ID."},{"name":"Account","description":"Credits, usage and shopper data deletion."}],"servers":[{"url":"https://api.genlook.app","description":"Production"}],"components":{"securitySchemes":{"x-api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key from https://platform.genlook.app (API keys page)."}},"schemas":{"ProductSpec":{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"description":"Your stable product identifier. Required on POST /products."},"title":{"type":"string","minLength":1,"description":"Product name as shoppers see it, e.g. \"Oversized cotton hoodie\"."},"description":{"type":"string","minLength":1,"description":"Full product description. Send it whenever you have it: it helps the AI identify the garment and render its cut, length and fit, and it makes the first try-on of a product faster."},"images":{"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/ProductImage"},"description":"Every photo of the product (front, back, on a model, flat lay): all are analyzed to make higher quality try-ons. Never split one product's photos into several products. Replaces the full image list on update. At least one image is required on first-create."},"metadata":{"type":"object","additionalProperties":{},"description":"Free-form JSON returned on GET /products/:externalId."},"validForDays":{"description":"Time-to-live in days. POST /products defaults to lifetime; inline /try-on defaults to 30 days on first create. `null` = explicit lifetime; one-shot calls force 7 days.","type":["integer","null"],"minimum":1,"maximum":365}},"additionalProperties":false,"description":"A product to render: reference an existing one by `externalId`, or describe it inline with `images: [{ source, classifications? }]`."},"ProductImage":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/ImageRef"},"classifications":{"type":"object","additionalProperties":{"type":"string"},"description":"Optional per-image classification overrides, e.g. {\"orientation\":\"front\"} or {\"on_model\":\"true\"}. Server-computed values fill in missing keys."}},"required":["source"],"additionalProperties":false,"description":"A single product image: a `source` image ref (remote `url` or multipart `fileKey`) plus optional per-image `classifications`."},"ImageRef":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Remote URL the server fetches. Mutually exclusive with `fileKey`."}},"required":["url"],"additionalProperties":false},{"type":"object","properties":{"fileKey":{"type":"string","minLength":1,"description":"Name of a multipart file field in the same request. Mutually exclusive with `url`."}},"required":["fileKey"],"additionalProperties":false}],"description":"An image provided by reference: exactly one of `url` (a remote image the server downloads) or `fileKey` (a multipart file field in the same request)."},"UploadImageBody":{"type":"object","properties":{"externalUserId":{"type":"string","minLength":1,"maxLength":255,"description":"Your opaque identifier for the end-user (no PII). Persisted so the upload can be wiped via DELETE /customers/:externalUserId (GDPR)."},"keepForDays":{"description":"How long the uploaded image is kept before deletion. One of 1, 3, 7. Falls back to the account default.","type":"number"},"crop":{"description":"Apply the 4:5 person-aware crop. Default true. Pass false to keep the original framing.","type":"boolean"},"requirePerson":{"description":"Refuse the upload with NO_PERSON_DETECTED (400) when no person is found in the photo. Leave it off for pet photos and for close-ups of feet or hands. Default false.","type":"boolean"}},"additionalProperties":false,"description":"Form-data body of POST /tryon/v1/images/upload."},"GenerateTryOn":{"type":"object","properties":{"products":{"minItems":1,"maxItems":4,"type":"array","items":{"$ref":"#/components/schemas/ProductSpec"},"description":"Products to render on the person, 1 to 4. Two or more are worn together in one result (for example a top, trousers and a jacket): only those garments change, the person keeps the rest of their outfit. Multi-product works with clothing only."},"person":{"$ref":"#/components/schemas/Person"},"externalUserId":{"type":"string","description":"Your opaque identifier for the end-user (no PII). Used for attribution and to wipe their data via DELETE /customers/:externalUserId (GDPR)."},"output":{"allOf":[{"$ref":"#/components/schemas/Output"}]},"mock":{"type":"boolean","description":"Test call: skips the AI and returns the person photo unchanged, fast. Costs no credit. Use it to build and test your integration."}},"required":["products","person"],"additionalProperties":false,"description":"Body of POST /tryon/v1/try-on."},"Person":{"type":"object","properties":{"image":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/PersonImageSource"}},"required":["source"],"additionalProperties":false},"keepHeadCovering":{"type":"boolean","description":"Keep the shopper's own head covering (hijab, headscarf, hat) or uncovered hair exactly as in their photo, and take nothing worn on the head from the product photos. Set it when the product is not sold with headwear, even if the model wears some. Default false."},"requirePerson":{"type":"boolean","description":"Refuse the try-on with NO_PERSON_DETECTED (400, not charged) when no person is found in the photo. Leave it off for pet photos and for close-ups of feet or hands. Applies to `url` and `fileKey` photos; for an uploaded `id`, set it on POST /images/upload. Default false."}},"required":["image"],"additionalProperties":false,"description":"The shopper to render the product on (their photo)."},"PersonImageSource":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Image id from a prior POST /images/upload. The recommended path."}},"required":["id"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Remote URL the server fetches. Mutually exclusive with `fileKey`."}},"required":["url"],"additionalProperties":false},{"type":"object","properties":{"fileKey":{"type":"string","minLength":1,"description":"Name of a multipart file field in the same request. Mutually exclusive with `url`."}},"required":["fileKey"],"additionalProperties":false}],"description":"The shopper photo to render the product on. Exactly one of `id` (reuse a prior upload — the only path that controls cropping), `url` (remote image), or `fileKey` (a multipart file field). `url`/`fileKey` are always cropped to a 4:5 person frame."},"Output":{"type":"object","properties":{"resolution":{"description":"Result size. \"default\": 1200 px on the long side (about 1 megapixel). \"2k\": about 4 megapixels (2048 x 2048 px in area, the person photo's aspect ratio kept), the same try-on with real high-resolution detail. \"2k\" adds 1 credit to the try-on (whatever its product count) and a few seconds.","allOf":[{"$ref":"#/components/schemas/OutputResolution"}]},"watermark":{"type":"boolean","description":"Composite the account watermark onto the result. Default true. No-op when no logo is configured."},"aiLabel":{"type":"boolean","description":"Composite the European Commission's 'AI MODIFIED' label onto the result (EU AI Act Article 50(4) transparency). Defaults to the account setting, which is on. Results always carry machine-readable AI-provenance metadata, whatever this is set to. Turning the visible label off makes you responsible for disclosing the manipulation to your end users."},"keepForDays":{"description":"How long the stored images for this generation (source + result) are kept before deletion. One of 1, 3, 7. Defaults to the account configuration.","type":"number"}},"additionalProperties":false,"description":"Result styling and retention for this generation."},"OutputResolution":{"type":"string","enum":["default","2k"]},"UsageRecord":{"type":"object","properties":{"generationId":{"type":"string"},"createdAt":{"type":"string","description":"When the generation was requested."},"completedAt":{"description":"When it completed or failed. Null while it is running.","type":["string","null"]},"status":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","FAILED"]},"credits":{"type":"number","description":"Credits charged. 0 for a failed (refunded) or mock generation. A completed batch item counts half its normal price."},"batchId":{"description":"Set for batch items.","type":["string","null"]},"apiKeyId":{"description":"The API key that made the call, when known.","type":["string","null"]}},"required":["generationId","createdAt","completedAt","status","credits","batchId","apiKeyId"],"additionalProperties":false},"CreateBatch":{"type":"object","properties":{"items":{"minItems":1,"maxItems":500,"type":"array","items":{"$ref":"#/components/schemas/BatchItem"},"description":"Try-ons to run, 1 to 500."}},"required":["items"],"additionalProperties":false,"description":"Body of POST /tryon/v1/batches: many try-ons at half price, run within 4 hours."},"BatchItem":{"type":"object","properties":{"products":{"minItems":1,"maxItems":4,"type":"array","items":{"$ref":"#/components/schemas/ProductSpec"},"description":"Products to render on the person, 1 to 4. Two or more are worn together in one result (for example a top, trousers and a jacket): only those garments change, the person keeps the rest of their outfit. Multi-product works with clothing only."},"person":{"$ref":"#/components/schemas/Person"},"externalUserId":{"type":"string","description":"Your opaque identifier for the end-user (no PII). Used for attribution and to wipe their data via DELETE /customers/:externalUserId (GDPR)."},"output":{"allOf":[{"$ref":"#/components/schemas/Output"}]},"customId":{"type":"string","minLength":1,"maxLength":200,"description":"Your id for this item, echoed back in the batch results."}},"required":["products","person"],"additionalProperties":false,"description":"One try-on of a batch. Same body as POST /try-on, JSON only: images by `url` or (person) by upload `id`, no multipart files."},"Error":{"type":"object","description":"Every error response. Branch on `code`: it is stable. `message` is for humans and may change.","required":["code","message","status"],"properties":{"code":{"type":"string","enum":["MISSING_API_KEY","INVALID_API_KEY","FORBIDDEN","BATCH_NOT_ALLOWED","VALIDATION_FAILED","EXTERNAL_ID_REQUIRED","PRODUCT_IMAGES_REQUIRED","CUSTOMER_IMAGE_REQUIRED","FILE_REQUIRED","MULTIPART_FILE_NOT_FOUND","INVALID_IMAGE_INPUT","INVALID_IMAGE","UNSUPPORTED_IMAGE_TYPE","CUSTOMER_IMAGE_FETCH_FAILED","PRODUCT_IMAGE_FETCH_FAILED","PRODUCT_IMAGE_TOO_SMALL","MISSING_REQUIRED_CLASSIFICATION","PERSON_IMAGE_TOO_SMALL","PERSON_IMAGE_BLANK","PERSON_TOO_FAR","NO_PERSON_DETECTED","CONTENT_POLICY_VIOLATION","BATCH_PRODUCT_NOT_SUPPORTED","MULTI_PRODUCT_NOT_SUPPORTED","IDEMPOTENCY_KEY_REUSED","FILE_TOO_LARGE","INSUFFICIENT_CREDITS","QUOTA_EXCEEDED","API_KEY_LIMIT_REACHED","RATE_LIMITED","PRODUCT_NOT_FOUND","GENERATION_NOT_FOUND","BATCH_NOT_FOUND","ACCOUNT_NOT_FOUND","ROUTE_NOT_FOUND","RESERVED_EXTERNAL_ID","BATCH_CANCELLED","IDEMPOTENCY_IN_PROGRESS","INTERNAL_ERROR","GENERATION_FAILED","GENERATION_TIMEOUT","BATCH_EXPIRED"],"description":"Stable error code."},"message":{"type":"string","description":"Human-readable description."},"status":{"type":"integer","description":"Same as the HTTP status."},"details":{"description":"Extra data for some codes: the invalid fields of `VALIDATION_FAILED`, `retryAfter` (seconds) of `RATE_LIMITED`, the `generationId` of a failed sync try-on."}}},"Product":{"type":"object","properties":{"externalId":{"type":"string","description":"Your stable product identifier."},"title":{"type":"string"},"description":{"type":"string"},"metadata":{"anyOf":[{},{"type":"null"}]},"validForDays":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Configured TTL in days, or null for lifetime products."},"expiresAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"ISO timestamp the product expires at if not used again. Null when the product is lifetime."},"lastUsedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"ISO timestamp of the last generation referencing this product."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"images":{"type":"array","items":{"type":"object","properties":{"sourceUrl":{"type":"string","description":"The original URL you supplied, or an opaque internal reference for multipart-uploaded bytes (`upload://…`). Stable identifier, not always fetchable."},"classifications":{"description":"Server-resolved classifications for this image (e.g. orientation, on_model). Empty when nothing has been classified yet.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"order":{"type":"integer","description":"0-indexed position in the supplied image list."}},"required":["sourceUrl","classifications","order"],"additionalProperties":false,"description":"A product image as it appears in API responses."}}},"required":["externalId","title","description","metadata","validForDays","expiresAt","lastUsedAt","createdAt","updatedAt","images"],"additionalProperties":false,"description":"A single product, as returned by GET/POST /tryon/v1/products[/...]."},"ProductList":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string","description":"Your stable product identifier."},"title":{"type":"string"},"description":{"type":"string"},"metadata":{"anyOf":[{},{"type":"null"}]},"validForDays":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Configured TTL in days, or null for lifetime products."},"expiresAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"ISO timestamp the product expires at if not used again. Null when the product is lifetime."},"lastUsedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}],"description":"ISO timestamp of the last generation referencing this product."},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"images":{"type":"array","items":{"type":"object","properties":{"sourceUrl":{"type":"string","description":"The original URL you supplied, or an opaque internal reference for multipart-uploaded bytes (`upload://…`). Stable identifier, not always fetchable."},"classifications":{"description":"Server-resolved classifications for this image (e.g. orientation, on_model). Empty when nothing has been classified yet.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"order":{"type":"integer","description":"0-indexed position in the supplied image list."}},"required":["sourceUrl","classifications","order"],"additionalProperties":false,"description":"A product image as it appears in API responses."}}},"required":["externalId","title","description","metadata","validForDays","expiresAt","lastUsedAt","createdAt","updatedAt","images"],"additionalProperties":false,"description":"A single product, as returned by GET/POST /tryon/v1/products[/...]."}},"nextCursor":{"type":"string","description":"Opaque cursor for the next page. Absent on the last page."},"hasMore":{"type":"boolean","description":"True when at least one more page exists."},"count":{"type":"integer","description":"Number of items in the current page."}},"required":["items","hasMore","count"],"additionalProperties":false,"description":"Paginated product list — response of GET /tryon/v1/products."},"ProductStats":{"type":"object","properties":{"totalGenerations":{"type":"integer","description":"Total generations against this product in the window, across all statuses."},"completedGenerations":{"type":"integer","description":"Subset of `totalGenerations` that reached COMPLETED."},"failedGenerations":{"type":"integer","description":"Subset of `totalGenerations` that ended in FAILED."},"avgGenerationTimeMs":{"type":"integer","description":"Average end-to-end duration of completed generations, in milliseconds. 0 when there are no completed generations."}},"required":["totalGenerations","completedGenerations","failedGenerations","avgGenerationTimeMs"],"additionalProperties":false,"description":"Per-product generation statistics. Response of GET /tryon/v1/products/:externalId/stats."},"UploadImageResponse":{"type":"object","properties":{"imageId":{"type":"string","description":"Opaque token. Pass as `person.image.source.id` on POST /try-on to reuse."},"imageUrl":{"type":"string","description":"Short-lived URL for previews. Re-upload (or re-fetch this response) for a fresh one."}},"required":["imageId","imageUrl"],"additionalProperties":false,"description":"Response of POST /tryon/v1/images/upload."},"GenerateTryOnResponse":{"type":"object","properties":{"generationId":{"type":"string","description":"Use with GET /generations/:id to poll status."},"status":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","FAILED"],"description":"Lifecycle status of a generation. Terminal states: COMPLETED, FAILED."},"productExternalId":{"type":"string","deprecated":true,"description":"Deprecated: use `productExternalIds[0]`. Still returned."},"productExternalIds":{"type":"array","items":{"type":"string"},"description":"Every product's externalId, or a server-generated `_anon_*` ID for one-shot products, in request order."}},"required":["generationId","status","productExternalId","productExternalIds"],"additionalProperties":false,"description":"Response of POST /tryon/v1/try-on."},"SyncTryOnResponse":{"type":"object","properties":{"generationId":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","FAILED"],"description":"Lifecycle status of a generation. Terminal states: COMPLETED, FAILED."},"resultImageUrl":{"type":"string","description":"Temporary signed URL. Present only when status is COMPLETED."},"errorMessage":{"type":"string","description":"Human-readable error description. Present only when status is FAILED."},"errorCode":{"type":"string","description":"Stable error enum value when the failure was raised as a typed error. Use this, not `errorMessage`, to branch."},"createdAt":{"type":"string","description":"ISO 8601 timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last status change."},"productExternalId":{"type":"string","deprecated":true,"description":"Deprecated: use `productExternalIds[0]`. Still returned."},"productExternalIds":{"type":"array","items":{"type":"string"},"description":"Every product's externalId, or a server-generated `_anon_*` ID for one-shot products, in request order."}},"required":["generationId","status","createdAt","updatedAt"],"additionalProperties":false},"GenerationStatusResponse":{"type":"object","properties":{"generationId":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","FAILED"],"description":"Lifecycle status of a generation. Terminal states: COMPLETED, FAILED."},"resultImageUrl":{"type":"string","description":"Temporary signed URL. Present only when status is COMPLETED."},"errorMessage":{"type":"string","description":"Human-readable error description. Present only when status is FAILED."},"errorCode":{"type":"string","description":"Stable error enum value when the failure was raised as a typed error. Use this, not `errorMessage`, to branch."},"createdAt":{"type":"string","description":"ISO 8601 timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last status change."}},"required":["generationId","status","createdAt","updatedAt"],"additionalProperties":false,"description":"Response of GET /tryon/v1/generations/:id."},"Credits":{"type":"object","properties":{"creditBalance":{"type":"integer","description":"Remaining try-on credits. Each successful generation consumes one."}},"required":["creditBalance"],"additionalProperties":false,"description":"Response of GET /tryon/v1/account/credits."},"UsageList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UsageRecord"}},"nextCursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"count":{"type":"integer"}},"required":["items","nextCursor","hasMore","count"],"additionalProperties":false,"description":"Response of GET /tryon/v1/usage."},"Batch":{"type":"object","properties":{"batchId":{"type":"string"},"status":{"type":"string","enum":["RUNNING","COMPLETED","CANCELLED","EXPIRED"],"description":"RUNNING until every item is done. EXPIRED: some items did not run within 4 hours. Terminal: COMPLETED, CANCELLED, EXPIRED."},"itemCount":{"type":"integer"},"completedCount":{"type":"integer"},"failedCount":{"type":"integer"},"reservedCredits":{"type":"integer","description":"Credits held at submit: half a credit per item, rounded up."},"chargedCredits":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Set once the batch is done: half a credit per completed item, rounded up. The rest of the reservation is returned."},"createdAt":{"type":"string"},"expiresAt":{"type":"string","description":"Items not run by then fail with BATCH_EXPIRED."},"items":{"type":"array","items":{"type":"object","properties":{"customId":{"type":["string","null"]},"generationId":{"type":"string"},"status":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","FAILED"],"description":"Lifecycle status of a generation. Terminal states: COMPLETED, FAILED."},"resultImageUrl":{"type":"string","description":"Temporary signed URL. Present only when status is COMPLETED."},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["customId","generationId","status"],"additionalProperties":false},"description":"Items in submit order, one page at a time."},"nextCursor":{"description":"Pass as `cursor` to read the next page of items.","type":["string","null"]}},"required":["batchId","status","itemCount","completedCount","failedCount","reservedCredits","chargedCredits","createdAt","expiresAt","items","nextCursor"],"additionalProperties":false,"description":"A batch and one page of its items."}},"headers":{"RequestId":{"description":"ID of this request. Include it when you contact support.","schema":{"type":"string"}},"RetryAfter":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":0}},"RateLimitLimit":{"description":"Try-ons the account may have running at once (20).","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Try-ons the account can still start right now, this one counted.","schema":{"type":"integer","minimum":0}},"IdempotencyReplayed":{"description":"`true` when this is the stored response of an earlier request with the same `Idempotency-Key`. Absent otherwise.","schema":{"type":"string","enum":["true"]}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Idempotency key: a unique value you choose (a UUID, 1 to 255 ASCII characters) that makes this call safe to retry. A repeat of the same request with the same key within 24 hours returns the first response (with `Idempotency-Replayed: true`) and creates and charges nothing new. The same key with a different body is refused with `IDEMPOTENCY_KEY_REUSED`. A failed request frees its key.","schema":{"type":"string","minLength":1,"maxLength":255},"example":"7f1c6c1e-3d0a-4c58-9d0e-8a1f1c2b3d4e"}}},"externalDocs":{"description":"Guides, SDK and changelog","url":"https://genlook.app/docs/tryon-api"},"security":[{"x-api-key":[]}],"webhooks":{"generation.completed":{"post":{"operationId":"webhook_generation_completed","tags":["Try-On"],"summary":"Webhook: generation.completed","description":"Sent to the account's webhook URL when it subscribed to `generation.completed` (platform.genlook.app, Webhooks). Answer with any 2xx. A failed delivery is retried up to 3 times.","parameters":[{"name":"X-Webhook-Signature","in":"header","required":false,"description":"`sha256=` followed by the hex HMAC-SHA256 of the raw request body, keyed with your webhook secret. Sent when the account has a secret.","schema":{"type":"string"}}],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event","timestamp","data"],"properties":{"event":{"type":"string","const":"generation.completed"},"timestamp":{"type":"string","format":"date-time","description":"When the event was sent."},"data":{"type":"object","required":["generationId","status","resultImageUrl","createdAt","completedAt"],"properties":{"generationId":{"type":"string"},"status":{"type":"string","const":"COMPLETED"},"resultImageUrl":{"type":"string","description":"Temporary signed URL of the result."},"generationTimeMs":{"type":["integer","null"],"description":"Generation time in milliseconds."},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}},"example":{"event":"generation.completed","timestamp":"2026-09-30T10:00:10.000Z","data":{"generationId":"cm8gen456xyz","status":"COMPLETED","resultImageUrl":"https://storage.googleapis.com/...","generationTimeMs":8200,"createdAt":"2026-09-30T10:00:00.000Z","completedAt":"2026-09-30T10:00:09.800Z"}}}}},"responses":{"200":{"description":"Received."}}}},"generation.failed":{"post":{"operationId":"webhook_generation_failed","tags":["Try-On"],"summary":"Webhook: generation.failed","description":"Sent to the account's webhook URL when it subscribed to `generation.failed` (platform.genlook.app, Webhooks). Answer with any 2xx. A failed delivery is retried up to 3 times.","parameters":[{"name":"X-Webhook-Signature","in":"header","required":false,"description":"`sha256=` followed by the hex HMAC-SHA256 of the raw request body, keyed with your webhook secret. Sent when the account has a secret.","schema":{"type":"string"}}],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event","timestamp","data"],"properties":{"event":{"type":"string","const":"generation.failed"},"timestamp":{"type":"string","format":"date-time","description":"When the event was sent."},"data":{"type":"object","required":["generationId","status","createdAt","failedAt"],"properties":{"generationId":{"type":"string"},"status":{"type":"string","const":"FAILED"},"errorCode":{"type":["string","null"],"description":"Stable error code. The credit is refunded."},"errorMessage":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"failedAt":{"type":"string","format":"date-time"}}}}},"example":{"event":"generation.failed","timestamp":"2026-09-30T10:00:10.000Z","data":{"generationId":"cm8gen456xyz","status":"FAILED","errorCode":"GENERATION_TIMEOUT","errorMessage":"The try-on generation did not finish within 60 seconds and was cancelled. The credit has been refunded; please retry.","createdAt":"2026-09-30T10:00:00.000Z","failedAt":"2026-09-30T10:01:00.000Z"}}}}},"responses":{"200":{"description":"Received."}}}},"batch.completed":{"post":{"operationId":"webhook_batch_completed","tags":["Batches"],"summary":"Webhook: batch.completed","description":"Sent to the account's webhook URL when it subscribed to `batch.completed` (platform.genlook.app, Webhooks). Answer with any 2xx. A failed delivery is retried up to 3 times.","parameters":[{"name":"X-Webhook-Signature","in":"header","required":false,"description":"`sha256=` followed by the hex HMAC-SHA256 of the raw request body, keyed with your webhook secret. Sent when the account has a secret.","schema":{"type":"string"}}],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event","timestamp","data"],"properties":{"event":{"type":"string","const":"batch.completed"},"timestamp":{"type":"string","format":"date-time","description":"When the event was sent."},"data":{"type":"object","required":["batchId","status","itemCount","completedCount","failedCount","chargedCredits"],"properties":{"batchId":{"type":"string"},"status":{"type":"string","enum":["RUNNING","COMPLETED","CANCELLED","EXPIRED"]},"itemCount":{"type":"integer"},"completedCount":{"type":"integer"},"failedCount":{"type":"integer"},"chargedCredits":{"type":"integer","description":"Half a credit per completed item, rounded up."}}}}},"example":{"event":"batch.completed","timestamp":"2026-09-30T10:00:10.000Z","data":{"batchId":"cm8batch123","status":"COMPLETED","itemCount":200,"completedCount":198,"failedCount":2,"chargedCredits":99}}}}},"responses":{"200":{"description":"Received."}}}}}}