Варианты

Набор вариантов

Набор именованный и конечный. Произвольной ширины не бывает — и это не упрощение, а решение: ?w=473 это и взрыв кеша, и бесплатный способ занять процессор машины.

Попробуйте

Какой вариант нужен блоку?

Задайте ширину блока на странице и плотность экрана. Правильный — самый маленький вариант, который ещё покрывает пиксели.

Ширина блока

thumbшириной 400 пкс
cardшириной 1 000 пкс
fullшириной 1 400 пкс

Отдавать:

Картинки

Имя	Ширина	Формат	Для чего
`thumb`	400 px	WebP, качество 82	списки, плитки, аватары
`card`	1000 px	WebP, качество 82	карточка товара, основная витрина
`full`	1400 px	WebP, качество 82	полноэкранный просмотр

Видео

Имя	Что это	Формат
`poster`	кадр-заставка, берётся с 10% длительности — не раньше 0,5 с и не позже 3 с	WebP до 1280 px
`preview`	беззвучный отрывок первых секунд	MP4 640 px
`hls`	основное воспроизведение, до трёх ступеней качества	HLS, H.264 + AAC
`mp4`	запасной путь для старых клиентов	прогрессивный MP4 1280 px

Ступени HLS — 640, 1280 и 1920 px. Ступень, которая шире оригинала, не делается: растянутая копия выглядит как наша вина.

Два правила, из-за которых вариант может не появиться

Не растягиваем

Если оригинал уже, чем ширина варианта, вариант остаётся размера оригинала, и ответ говорит об этом честно — в полях w и h стоят настоящие числа.

Одинаковые копии не заводятся дважды

Если после этого две ширины сошлись бы в один и тот же файл, второй адрес не заводится. Два побайтово одинаковых файла по разным адресам — это два скачивания одного и того же на телефоне человека.

POST /api/v1/put?kind=prodimg&key=42&variants=card,full   ← оригинал 300×200
    → {
        "ow": 300, "oh": 200,
        "variants": { "card": { "w": 300, "h": 200, … } },
        "skipped":  { "full": "оригинал шириной 300 px — вариант совпал бы байт в байт с «card»" }
      }

Поэтому набор вариантов в ответе всегда надо читать, а не предполагать: попросили два — могли получить один, и это нормальный, ожидаемый ответ.

Как заводится новый вариант

Новый вариант появляется в конфигурации сервиса и у арендатора в ту же задачу. Заводить его «пока только на сервисе» смысла нет: адрес всё равно узнаётся из ответа, а незапрошенный вариант просто занимал бы место.

Уже загруженные объекты можно пересобрать в новый вариант без повторной отправки файла — оригинал хранится у нас в холодном дереве и наружу не отдаётся никогда. Ради этого он и хранится.