Skip to content
MediuxDocs

Build image URLs

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:

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

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

AreaHoldsFound in
assetsCommunity artworkSets, Assets, Lists and creator pages
metadataProvider images (TMDB, IGDB) that identify a titlemetadataImages on titles and People
usersCreator avatars and profile backdropsCreator profiles
You wantURL
The original filehttps://img.mediux.io/{area}/original/{id}.{extension}
A resized AVIFhttps://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
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.

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:

extensionMedia type
avifimage/avif
jpg, jpegimage/jpeg
pngimage/png
webpimage/webp
svgimage/svg+xml
icoimage/vnd.microsoft.icon

Each slot has its own sizes, listed below and in GET /config 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.

SlotSizes
posterplaceholder, w300
backdropplaceholder, w300, w1920
logoplaceholder, w300
squareArtplaceholder, w300
titlecardplaceholder, w300
thumbplaceholder, w300
coverplaceholder, w300
heroplaceholder, w300, w1920
wideCoverplaceholder, w300
backgroundplaceholder, w300, w1920
squareCoverplaceholder, w300
iconplaceholder, w300, plus 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.

SlotSizes
backdropplaceholder, w300, w780, w1280, w1920, w3840
logow300, w1280
posterplaceholder, w300, w780
profileplaceholder, w300, w780
SlotSizes
avatarplaceholder, w92, w300
backdropplaceholder, w300, w1920

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.