An agent that recommends a product has to show it. Media carries every image and video we hold, with the role it plays, its true dimensions, and pre-computed renditions so you are not resizing on the fly.
| Field | Type | Notes |
|---|---|---|
| media_id ·always | string | Stable. |
| role ·always | enum | primary | gallery | detail | lifestyle | size_chart | video. |
| url ·always | string | Full-resolution source. |
| renditions | object | Pre-sized variants: thumb (200px), card (400px), detail (800px), full (1600px). |
| width / height | int | True pixel dimensions. Aspect ratios differ wildly between sellers. |
| variant_ids | string[] | Which variants this image depicts. Empty means it applies to the product as a whole. |
| position | int | The seller's own ordering. Position 1 is usually, not always, the primary. |
| alt | string | null | Alt text where published. |
{
"media_id": "med_71ka2",
"role": "primary",
"url": "https://cdn.commercecensus.com/m/71ka2/full.jpg",
"renditions": {
"thumb": "https://cdn.commercecensus.com/m/71ka2/200.jpg",
"card": "https://cdn.commercecensus.com/m/71ka2/400.jpg",
"detail": "https://cdn.commercecensus.com/m/71ka2/800.jpg",
"full": "https://cdn.commercecensus.com/m/71ka2/1600.jpg"
},
"width": 1430, "height": 1430,
"variant_ids": ["var_2c81f"],
"position": 1,
"alt": "Sony WH-1000XM5 in midnight black, three-quarter view"
}Seller image URLs rotate, expire and are frequently blocked from other origins. Hot-linking produces a product page full of broken images three months later, which is why renditions are stored and served rather than proxied.
Almost no seller labels an image as a size chart or a lifestyle shot. Role is classified, which is what makes it possible to ask for the one clean product photo instead of the twentieth lifestyle image.
About 64% of variants carry a distinct primary image; the rest inherit the product's. When a colour has no photo of its own, the response says so rather than showing the wrong colour.