# Build image URLs

> Turn an image ID from any response into a full-size, resized or JPG image URL.

Responses never contain image URLs. Each image is an ID and the original's file
extension, and you build the URL you need on `https://img.mediux.io`:

```json
"poster": { "id": "6d5b60e2-ad28-4e03-8dcf-dddbcbdec4fc", "extension": "png" }
```

## Pick the area

The first part of the path says where the image comes from:

| Area       | Holds                                               | Found in                                  |
| ---------- | --------------------------------------------------- | ----------------------------------------- |
| `assets`   | Community artwork                                   | Sets, Assets, Lists and creator pages     |
| `metadata` | Provider images (TMDB, IGDB) that identify a title  | `metadataImages` on titles and People     |
| `users`    | Creator avatars and profile backdrops               | Creator profiles                          |

## Build the URL

| You want                    | URL                                                    |
| --------------------------- | ------------------------------------------------------ |
| The original file           | `https://img.mediux.io/{area}/original/{id}.{extension}` |
| A resized AVIF              | `https://img.mediux.io/{area}/{size}/{id}.avif`        |
| A JPG copy (community art)  | `https://img.mediux.io/assets/jpg/{id}.jpg`            |
| An ICO (Game Icons)         | `https://img.mediux.io/assets/ico/{id}.ico`            |

```js
const host = "https://img.mediux.io";

const original = (area, { id, extension }) =>
  `${host}/${area}/original/${id}.${extension}`;

const resized = (area, { id }, size) => `${host}/${area}/${size}/${id}.avif`;

// A Set's poster as a grid thumbnail, and its full-size file.
const thumb = resized("assets", set.movie.poster, "w300");
const full = original("assets", set.movie.poster);
```

`placeholder` is a tiny blurred AVIF to show while the real image loads.

## File types

Resized images are always AVIF, JPG copies are JPEG and Game Icons also come as
ICO. An original keeps its own type, given by `extension`:

| `extension`   | Media type                 |
| ------------- | -------------------------- |
| `avif`        | `image/avif`               |
| `jpg`, `jpeg` | `image/jpeg`               |
| `png`         | `image/png`                |
| `webp`        | `image/webp`               |
| `svg`         | `image/svg+xml`            |
| `ico`         | `image/vnd.microsoft.icon` |

## Sizes

Each slot has its own sizes, listed below and in
[`GET /config`](https://docs-preview.mediux.io/api/reference/reference/retrieve-config.md) at runtime. A raster
image only has the sizes up to its own width: if a size returns `404`, use the
next smaller one, then the original. An SVG has every size.

### Community artwork (`assets`)

| Slot | Sizes |
| ---- | ----- |
| `poster` | `placeholder`, `w300` |
| `backdrop` | `placeholder`, `w300`, `w1920` |
| `logo` | `placeholder`, `w300` |
| `squareArt` | `placeholder`, `w300` |
| `titlecard` | `placeholder`, `w300` |
| `thumb` | `placeholder`, `w300` |
| `cover` | `placeholder`, `w300` |
| `hero` | `placeholder`, `w300`, `w1920` |
| `wideCover` | `placeholder`, `w300` |
| `background` | `placeholder`, `w300`, `w1920` |
| `squareCover` | `placeholder`, `w300` |
| `icon` | `placeholder`, `w300`, `ico` |

JPG copies suit tools that can't read AVIF, such as some media servers. Check
`images.areas.assets.jpg` in `/config` before you use them: while it's `false`,
use the original instead. Logos, Icons and SVG originals have no JPG copy. A JPG
copy fits inside the box `images.areas.assets.jpgFits` gives for its slot, such
as 1000 × 1500 for a poster, and is never enlarged. Where `crop` is `true` (Game
launcher art), a file with another shape is centre-cropped to the box's shape.

### Provider images (`metadata`)

| Slot | Sizes |
| ---- | ----- |
| `backdrop` | `placeholder`, `w300`, `w780`, `w1280`, `w1920`, `w3840` |
| `logo` | `w300`, `w1280` |
| `poster` | `placeholder`, `w300`, `w780` |
| `profile` | `placeholder`, `w300`, `w780` |

### Creator images (`users`)

| Slot | Sizes |
| ---- | ----- |
| `avatar` | `placeholder`, `w92`, `w300` |
| `backdrop` | `placeholder`, `w300`, `w1920` |

## Keep URLs fresh

An image URL always shows the same file, so browsers and your own cache can keep
it for a year. When a creator replaces artwork, the new file gets a new ID and
the old URL may stop working. Store IDs from the API rather than URLs you built
long ago, and read them again when you refresh your data.
