API / Identity & catalogue
Every image we hold for a product and its variants, with pre-computed renditions, true dimensions and the role each one plays.
GET /v1/products/{id}/media
| Name | Type | Notes |
|---|---|---|
| variant_id | string | Restrict to imagery for one variant. |
| role | enum | primary | gallery | detail | lifestyle | size_chart | video. |
| rendition | enum | thumb 200 | card 400 | detail 800 | full 1600. |
GET /v1/products/prd_8Fk2xQ/media?role=primary&rendition=card
→ 200
{ "media": [
{ "media_id": "med_71ka2", "role": "primary",
"url": "https://cdn.commercecensus.com/m/71ka2/400.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"],
"alt": "Sony WH-1000XM5 in midnight black, three-quarter view" } ],
"counts": { "total": 12, "primary": 1, "gallery": 8, "detail": 3 } }Images are stored and served from our CDN rather than hot-linked. Seller image URLs rotate, expire and are frequently blocked cross-origin — hot-linking produces a catalogue full of broken images three months later.
Role is classified, not declared. Almost no seller labels a size chart or a lifestyle shot, so asking for `role=primary` is the only reliable way to get the one clean product photo instead of the twentieth styled image.
Measured across nine industries: median 5 images per product, but electronics runs to 18 and food to 5. About 64% of variants carry a distinct primary image; the rest inherit the product's, and the response says which.