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

# API v1 images

> Render responsive hotel, room type, and visit type images from API v1.

Hotel, room type, and visit type responses expose the first image directly on
each object. Embedded room types and visit types use the same image fields as
their top-level responses.

## Response shape

Where `image` and `thumbnail` already exist, their values remain unchanged.
The responsive metadata is additive:

```json theme={null}
{
  "image": "https://files.example.com/production/hotels/example/photo.jpg",
  "thumbnail": "https://files.example.com/production/thumbnails/hotels/example/photo.webp",
  "width": 2400,
  "height": 1600,
  "alt": {
    "cs_CZ": "Průčelí lázeňského hotelu"
  },
  "variants": {
    "w480": "https://files.example.com/production/thumbnails/v2/hotels/example/generation/w480.webp",
    "w960": "https://files.example.com/production/thumbnails/v2/hotels/example/generation/w960.webp",
    "w1440": "https://files.example.com/production/thumbnails/v2/hotels/example/generation/w1440.webp",
    "w1920": "https://files.example.com/production/thumbnails/v2/hotels/example/generation/w1920.webp"
  }
}
```

| Field             | Meaning                                                                    |
| ----------------- | -------------------------------------------------------------------------- |
| `image`           | Original image URL. Use it for a full-size view and as the final fallback. |
| `thumbnail`       | Legacy preview URL. It can be `null`.                                      |
| `width`, `height` | Intrinsic dimensions of the oriented original, or `null` when unavailable. |
| `alt`             | Localized alternative text selected by `Accept-Language`.                  |
| `variants`        | Available WebP URLs keyed by target width.                                 |

All six fields describe only the first image. When the object has no image,
`image`, `thumbnail`, `width`, and `height` are `null`, `variants` is an empty
object, and `alt` contains the requested locale keys with `null` values.

## Build a responsive image

Use only the variant URLs returned by the API. Do not construct a URL for a
missing width. Images are never enlarged, so an 1100-pixel original has `w480`
and `w960`, but no larger variants. Pass a hotel, room type, or visit type
object as `image`.

```js theme={null}
const widths = [480, 960, 1440, 1920];

const srcset = widths
  .flatMap((width) => {
    const url = image.variants[`w${width}`];
    return url ? [`${url} ${width}w`] : [];
  })
  .join(", ");

const src =
  image.variants.w960 ?? image.variants.w480 ?? image.thumbnail ?? image.image;
```

Set `srcset` only when the resulting string is non-empty. Set `sizes` to the
actual layout slot, for example `(max-width: 768px) 100vw, 50vw`. The browser
then selects the best available variant for the viewport and device pixel
density.

Use non-null `width` and `height` as the HTML intrinsic dimensions. They reserve
the correct aspect ratio before the image loads. Do not replace them with the
CSS slot size.

```html theme={null}
<img
  src="<selected src>"
  srcset="<generated srcset>"
  sizes="(max-width: 768px) 100vw, 50vw"
  width="2400"
  height="1600"
  alt="Spa hotel exterior"
  loading="lazy"
/>
```

Use `loading="eager"` and `fetchpriority="high"` only for the single image that
is the page's likely largest contentful paint (LCP). Lazy-load images outside
the initial viewport.

## Empty variants and fallbacks

An empty `variants` object means that no responsive variant is available. It
does not mean that processing is still pending. Omit `srcset` and use
`thumbnail ?? image` as `src`.

There are two possible cases:

* A small original can have known `width` and `height` but no variant because
  its width is below 480 pixels.
* An unavailable legacy image has `width: null`, `height: null`, and
  `variants: {}`.

As a final error fallback, remove `srcset` and try `thumbnail`, then `image`.
This is useful if a cached client encounters a missing variant, but it does not
replace normal HTTP error monitoring.

## Alternative text

`alt` follows [`Accept-Language`](/api/v1/localization). The response contains
the requested language keys:

* A missing or `null` hotel image translation falls back to the localized
  hotel name.
* A missing or `null` room image translation falls back to the localized room
  category, or `null` when that category translation is unavailable.
* A missing or `null` visit type image translation falls back to the localized
  visit type name.
* An explicit empty string remains `""`. Preserve it when the image is
  decorative.
* A non-empty stored value is trimmed.

The API provides recommended alternative text. Your client can still use
`alt=""` when the image is decorative or redundant in its rendered context.

## Compatibility

The responsive fields are additive. Existing hotel and room type `image` and
`thumbnail` values retain their behavior. Visit types expose the same
first-image fields.

See the [Hotels endpoint](/api/v1/reference/catalog/get-hotels), [Hotel
endpoint](/api/v1/reference/catalog/get-hotel), and [Visit types
endpoint](/api/v1/reference/get-visit-types).