Start a generation

POST /generations

Queue a virtual try-on generation using the customer photo and Shopify product. Save the returned job ID and poll for completion.

Request

Authentication: X-Antla-SDK-Key: YOUR_ANTLA_SDK_KEY. Content-Type: application/json.

Uses the shared IP rate limit. See Errors and rate limits.

Body field	Type	Required	Description
funnelId	number	Yes	Positive integer, belonging to this store and assigned to the product.
productId	string or number	Yes	Product numeric ID, numeric string or full Product GID. Prefer a string/GID to avoid precision loss.
variantId	string or number	Yes	Variant numeric ID, numeric string or full ProductVariant GID, belonging to this product.
imageUrl	string	Yes	Publicly retrievable customer photo URL.
uniqueUserId	string	No	Non-empty saved Antla visitor ID.
customerEmail	string	No	Valid email; registers the visitor and supplies generation-linked Klaviyo data. Trim before sending.
moreLooksConsent	boolean	No	Shopper’s actual consent choice.

Example request

curl --fail-with-body -X POST \
  "https://app-antla.com/api/headless/generations" \
  -H "X-Antla-SDK-Key: YOUR_ANTLA_SDK_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "funnelId": 123,
  "productId": "gid://shopify/Product/123",
  "variantId": "gid://shopify/ProductVariant/456",
  "imageUrl": "https://YOUR_PUBLIC_IMAGE_HOST/customer-photo.jpg"
}'

Successful response

HTTP 200, JSON envelope:

{
  "data": {
    "jobId": "c45451c0-b02c-4c90-8c6e-0779edb01996",
    "etaSeconds": 40,
    "uniqueUserId": null
  }
}

A successful request returns HTTP 200. etaSeconds is an estimate. uniqueUserId can be null. The output image is not in this response.

Before queueing, the server checks the funnel’s store, the product, the tag antla_in_funnel_<id>, variant membership, a product image, the email gate, the customer try-on limit, and merchant credits. It uses the variant image when one exists, otherwise the first product image. It does not check Storefront publication or availableForSale. Check those in your own catalog.

Do not send a model, prompt or garment image override. Those are controlled by the merchant’s Antla funnel/configuration.

Do not automatically retry after an ambiguous network failure or 5xx. No idempotency-key contract is implemented, and a job or credit operation may already have happened.

Errors

Status	When
400	Invalid JSON or body, missing product image, or registration failure such as Unable to identify session or Email already registered.
403	The product is not in this funnel. That body is { "error": "Product is not assigned to this funnel" } and has no code. Or code is EMAIL_REQUIRED.
404	Funnel, product, or variant is missing or belongs to another store.
429	Shared IP limit, or code TRY_ON_LIMIT_REACHED. Only the IP limit includes Retry-After.
500	Shopify, credits, or the queue. Credit and queue failures return { "error": "Could not create generation" } and have no credit-specific code.

A sold-out variant is not rejected here. Retry rules are in Errors and rate limits.