Product variants

A product variant is a specific SKU of a product — a size, color, bundle, or other variation. Each variant has its own ordered list of images that the API uses during image ad generation.

Mental model

If your product is "Trail Runner Pro", variants are "Red / 10", "Black / 11", "Limited Edition Blue". When you generate an image ad and pass product_variant_id, the API uses that variant's images instead of the default product images. Useful when different SKUs need different hero shots.

ID prefix: pv_.

Fields

Endpoints

Common patterns

Create a variant with images

const response = await fetch("https://api.staticadslab.com/v1/product-variants", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    product_id: "prod_YOUR_PRODUCT_ID",
    name: "Red / Large",
    image_ids: ["img_red_lg_hero", "img_red_lg_lifestyle"],
  }),
});

Use a variant when generating an image ad

await fetch("https://api.staticadslab.com/v1/image-ads", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    design_template_id: "dt_...",
    brand_id: "brand_...",
    product_id: "prod_...",
    audience_id: "aud_...",
    product_variant_id: "pv_red_lg",
  }),
});

Pitfalls

• Variants have no description field. Variant-specific copy comes from the product description and the audience.
• image_ids order matters — the API treats earlier IDs as primary candidates for hero shots.
• A variant must belong to a product in the same brand as the image ad request.

Related

• Products
• Images

Prompt for your agent

Read https://www.staticadslab.com/docs/resources/product-variants.mdx and create variants for product prod_YOUR_PRODUCT_ID. I have a CSV with columns name, image_urls — for each row, upload the images, then create the variant with those image IDs.