> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychannel3.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<table>
  <thead>
    <tr>
      <th>Shot type</th>
      <th>Examples</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `hero`

        Primary product shot — usually front-facing on a clean background.
      </td>

      <td>
        ![Hero product shot](https://cdn.trychannel3.com/0b8f2b1a-883f-436c-ab53-d80c68241a59)
      </td>

      <td>
        ![Hero product shot](https://cdn.trychannel3.com/1bcc71f2-bc82-4a64-8738-43aa12d9a1a2)
      </td>
    </tr>

    <tr>
      <td>
        `lifestyle`

        Styled or environmental context — editorial settings and mood shots.
      </td>

      <td>
        ![Lifestyle product shot](https://cdn.trychannel3.com/96e752f3-d415-4a8f-b5fe-a8731694eacb)
      </td>

      <td>
        ![Lifestyle product shot](https://cdn.trychannel3.com/f2a1ccc2-0622-4d19-aab0-7ea82ca4c1c2)
      </td>
    </tr>

    <tr>
      <td>
        `on_model`

        Model wearing the product — useful for fit and virtual try-on.
      </td>

      <td>
        ![Product on model](https://cdn.trychannel3.com/36632687-ce6c-4611-b095-e15a10bfd308)
      </td>

      <td>
        ![Product on model](https://cdn.trychannel3.com/eb3b7806-ccab-40b1-9807-35925417f89b)
      </td>
    </tr>

    <tr>
      <td>
        `detail`

        Close-up of fabric, stitching, hardware, or texture.
      </td>

      <td>
        ![Product detail shot](https://cdn.trychannel3.com/61a93a1e-5656-4022-b401-392fe0409bea)
      </td>

      <td>
        ![Product detail shot](https://cdn.trychannel3.com/fb31f56d-71c4-4b04-af9e-02ffb706fbea)
      </td>
    </tr>

    <tr>
      <td>
        `flat_lay`

        Product photographed flat from above.
      </td>

      <td>
        ![Product flat lay](https://cdn.trychannel3.com/42b0812b-aa61-43e2-8618-c8d8823ad06b)
      </td>

      <td>
        ![Product flat lay](https://cdn.trychannel3.com/9866a3e2-8c97-4b3d-a4bc-066467dd71a0)
      </td>
    </tr>

    <tr>
      <td>
        `in_use`

        Product actively being used, worn, or opened in context.
      </td>

      <td>
        ![Product in use](https://cdn.trychannel3.com/564431a8-420a-4883-82d2-36169de91e12)
      </td>

      <td>
        ![Product in use](https://cdn.trychannel3.com/3449e130-a01f-4003-9810-8cf429b16d7c)
      </td>
    </tr>

    <tr>
      <td>
        `scale_reference`

        Size context — dimensions annotated or shown next to reference
        objects.
      </td>

      <td>
        ![Product scale reference](https://cdn.trychannel3.com/6afbc93f-9bf7-4cda-b355-32df52438186)
      </td>

      <td>
        ![Product scale reference](https://cdn.trychannel3.com/ea30903a-e353-4f4e-9282-69727519827f)
      </td>
    </tr>

    <tr>
      <td>
        `packaging`

        Product in retail box, bag, or packaging.
      </td>

      <td>
        ![Product packaging](https://cdn.trychannel3.com/fdd791e6-bb86-407e-8909-4528e249331a)
      </td>

      <td>
        ![Product packaging](https://cdn.trychannel3.com/6be1bd06-adea-4804-89a0-1edda83b088f)
      </td>
    </tr>

    <tr>
      <td>
        `size_chart`

        Sizing tables or measurement diagrams.
      </td>

      <td>
        ![Size chart for the men's T-shirt, showing width and length measurements for different sizes](https://cdn.trychannel3.com/0b6bf047-9a84-42cd-84c7-0f151e221eb8)
      </td>

      <td>
        ![Dimensional diagram showing the size of the dishwasher](https://cdn.trychannel3.com/b569745a-87d8-4d3f-917f-1d1cb81ffcc0)
      </td>
    </tr>

    <tr>
      <td>
        `product_information`

        Specs, features, or infographics about the product.
      </td>

      <td>
        ![Comparison of different lip products and their features](https://cdn.trychannel3.com/bb58f595-8752-43d0-8f9c-14ff24da795e)
      </td>

      <td>
        ![Infographic showing drop protection and screen protection features of the phone case](https://cdn.trychannel3.com/dd179691-1e89-4e73-be4a-9d0da8184a21)
      </td>
    </tr>

    <tr>
      <td>
        `merchant_information`

        Retailer marketing — banners, warranties, and store messaging (not the
        product itself).
      </td>

      <td>
        ![Merchant information shot](https://cdn.trychannel3.com/5a53d4ec-fa3e-4542-acd9-71af1aee629f)
      </td>

      <td>
        ![Merchant information shot](https://cdn.trychannel3.com/2518a897-67f3-477b-8b67-ed49a8d76634)
      </td>
    </tr>
  </tbody>
</table>

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:

1. Square aspect ratio
2. Uniform background
3. 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](http://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](https://mintcdn.com/channel3/oRJ2GuCXjnj_w_5r/public/changelog/update5-nordstrom-before.png?fit=max\&auto=format\&n=oRJ2GuCXjnj_w_5r\&q=85\&s=f7cc4c45069086f025fdc19ceba52aeb)

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](https://mintcdn.com/channel3/oRJ2GuCXjnj_w_5r/public/changelog/update5-nordstrom-after.png?fit=max\&auto=format\&n=oRJ2GuCXjnj_w_5r\&q=85\&s=5e732d847c7ba278fbc50093269edb06)

## Prefer cleaned images in grids

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

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

> [!NOTE]
>
> **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`.

> **[Image Search](/guides/image-search)**
>
> Visual search is a common place to surface cleaned images in a grid.

> **[Color Filters](/guides/color-filters)**
>
> Combine color filters with cleaned images for palette-matched, uniform
> grids.

> **[UI Components](/guides/ui-and-hooks)**
>
> Channel3 components can prefer cleaned images in product cards
> automatically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.