Variants

The set of variants

The set is named and finite. There is no arbitrary width — and that is a decision, not a simplification: ?w=473 is both a cache explosion and a free way to occupy the machine's processor.

Try it

Which variant does a block need?

Set the width of the block on the page and the screen density. The smallest variant that still covers the pixels is the right one.

Block width

thumb400 px wide
card1 000 px wide
full1 400 px wide

Serve:

Images

Name	Width	Format	What for
`thumb`	400 px	WebP, quality 82	lists, tiles, avatars
`card`	1000 px	WebP, quality 82	a product card, the main storefront
`full`	1400 px	WebP, quality 82	full-screen viewing

Video

Name	What it is	Format
`poster`	a still frame, taken at 10% of the duration — no earlier than second 0.5 and no later than second 3	WebP up to 1280 px
`preview`	a silent clip of the first seconds	MP4 640 px
`hls`	the main playback path, up to three quality steps	HLS, H.264 + AAC
`mp4`	a fallback for older clients	progressive MP4 1280 px

The HLS steps are 640, 1280 and 1920 px. A step wider than the original is not made: a stretched copy looks like our fault.

Two rules under which a variant may not appear

We do not stretch

If the original is narrower than the variant's width, the variant stays at the original's size, and the answer says so honestly — the w and h fields carry the real numbers.

Identical copies are not stored twice

If two widths would come out as the very same file, the second address is not created. Two byte-identical files at two addresses are two downloads of the same thing onto someone's phone.

POST /api/v1/put?kind=prodimg&key=42&variants=card,full   ← original 300×200
    → {
        "ow": 300, "oh": 200,
        "variants": { "card": { "w": 300, "h": 200, … } },
        "skipped":  { "full": "the original is 300 px wide — the variant would be byte-identical to “card”" }
      }

So the set of variants in the answer always has to be read, not assumed: you asked for two and may have got one, and that is a normal, expected answer.

How a new variant is added

A new variant appears in the service configuration and at the tenant in the same task. Adding it “on the service only” makes no sense: the address is learnt from the answer anyway, and an unrequested variant would simply take up space.

Objects already uploaded can be rebuilt into a new variant without sending the file again — the original is kept in our cold tree and is never served outward. That is what it is kept for.