Images

High-quality images are returned with each product. We classify every image with AI and attach metadata on the ProductImage type — including shot_type, AI-generated alt_text, and an optional cleaned_url that shows a centered product on a clean background.

Shot types

Every image is classified into a shot_type so you can curate what shoppers see. Building a scrollable grid? Prefer hero images. Want a mood-board feel? Try lifestyle. Filter out size_chart from carousels. Use on_model for fit and virtual try-on flows. Each product can have multiple images across types. Read shot_type on any image in the images array:

TypeScript

const heroImages = product.images.filter((img) => img.shot_type === "hero");
const withoutCharts = product.images.filter(
  (img) => img.shot_type !== "size_chart",
);

Examples below are from major retailers in our catalog — RelevanceLevel.MAJOR (relevance score 4), with AI-analyzed, displayable images.

Shot type	Examples
`hero` Primary product shot — usually front-facing on a clean background.
`lifestyle` Styled or environmental context — editorial settings and mood shots.
`on_model` Model wearing the product — useful for fit and virtual try-on.
`detail` Close-up of fabric, stitching, hardware, or texture.
`flat_lay` Product photographed flat from above.
`in_use` Product actively being used, worn, or opened in context.
`scale_reference` Size context — dimensions annotated or shown next to reference objects.
`packaging` Product in retail box, bag, or packaging.
`size_chart` Sizing tables or measurement diagrams.
`product_information` Specs, features, or infographics about the product.
`merchant_information` Retailer marketing — banners, warranties, and store messaging (not the product itself).

Because images come in various styles and aspect ratios, we also provide cleaned images — square aspect ratios and uniform backgrounds that make product grids look consistent.

Cleaned images

Cleaned images have:

Square aspect ratio
Uniform background
Centered product

When a cleaned variant exists for a shot, it is returned on the same ProductImage as cleaned_url. The url field stays the regular hosted hero shot; use cleaned_url in product grids. is_cleaned_image is deprecated and always false. Use cleaned_url ?? url for product grids. Take nordstrom.com on our dashboard. Before cleaned images, the product grid is good, but bad aspect ratios stick out and on-model shots break up the layout.

A Nordstrom product grid before cleaned images, with mismatched aspect ratios and on-model shots — Before: inconsistent aspect ratios and on-model shots break up the grid.

With cleaned images, every tile is a square lay-flat shot — on-model photos are replaced, and narrow crops (like sunglasses) are padded to square.

The same Nordstrom product grid after cleaned images, with uniform square tiles — After: every tile is a square, monochromatic lay-flat shot.

Prefer cleaned images in grids

When displaying search or similar-product results, pick the cleaned image when one is available:

TypeScript

function productImageUrl(
  image: ProductImage,
  { preferCleaned = false } = {},
): string {
  if (preferCleaned) return image.cleaned_url ?? image.url;
  return image.url;
}

const heroImage =
  product.images.find((img) => img.is_main_image) ?? product.images[0];
const gridUrl = productImageUrl(heroImage, { preferCleaned: true });

This works on any product response that includes images — search, lookup, and product detail all expose the same ProductImage model.

Migration: Older API responses duplicated cleaned shots as a second images[] entry with is_cleaned_image: true. That duplicate row is removed; use cleaned_url ?? url on the original shot instead. The is_cleaned_image field remains for backward compatibility but is always false.

Getting Started

Make a Search

Get Product Data

Checkout

Pricing, Reporting, and Commissions

Build

Integrate

FAQ

Shot types

Cleaned images

Prefer cleaned images in grids

​Shot types

​Cleaned images

​Prefer cleaned images in grids

Shot types

Cleaned images

Prefer cleaned images in grids