Images

Simkl returns image paths (not full URLs) inside poster, fanart, episode, and avatar fields. You build the final URL by combining a domain prefix, a category prefix, the image path, a size suffix, and a file extension. We strongly recommend serving images through wsrv.nl, a free image proxy that caches, resizes, and converts on the fly. This minimizes load on Simkl’s servers and gives you free image transformations. All examples below append &q=90 to the wsrv URL — this matches origin image quality. Without it, wsrv’s default &q=80 re-encodes images at noticeably smaller filesize and lower quality. Setting &q= above 90 is rarely useful — sizes balloon past origin without visible quality gain.

Anatomy of a URL

Image URL anatomy: category, image path, size, extension

Part	Example	Notes
Proxy + domain	`https://wsrv.nl/?url=https://simkl.in`	Always start with this.
Category	`/posters/`	One of `/posters/`, `/fanart/`, `/episodes/`, `/avatars/`.
Image path	`74/74415673dcdc9cdd`	The value from the API field (`poster`, `fanart`, etc.).
Size suffix	`_w`	Determines pixel size — see each section below.
Extension	`.webp`	Always `.webp` for posters, episodes, and every fanart size except `_d`. Two exceptions: fanart `_d` is `.jpg` only (details), avatars are `.jpg` only (details).
Quality	`&q=90`	Quality parameter for the wsrv proxy. `&q=90` matches origin quality (default `&q=80` reduces quality and filesize). Setting `&q=` above 90 is rarely useful — sizes balloon past origin without visible quality gain.

Use .webp for posters, episodes, and fanart.Two .jpg exceptions:

Fanart _d — original-resolution, darker tone, smaller filesize than _medium.webp. JPG only.
Avatars — small enough that the format doesn’t matter; served as JPG without the wsrv.nl proxy.

Code samples

Each tab covers a different real-world scenario. All samples handle missing/null paths by falling back to the wsrv-proxied placeholders documented in Fallback when images are missing.

Single helper covering all four kinds, with null-safe fallback for posters.

const SIMKL_IMG_BASE = 'https://wsrv.nl/?url=https://simkl.in';

function imageUrl(path, kind = 'posters', size = '_w', ext = '.webp') {
  if (!path) {
    if (kind !== 'posters') return null; // hide fanart/episode/avatar — no placeholder
    const ph = size === '_s' ? '_s' : '_c';
    return `${SIMKL_IMG_BASE}/poster_no_pic${ph}.png`;
  }
  return `${SIMKL_IMG_BASE}/${kind}/${path}${size}${ext}&q=90`;
}

imageUrl('74/74415673dcdc9cdd', 'posters', '_w');
// → https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_w.webp&q=90

imageUrl(null, 'posters', '_c');
// → https://wsrv.nl/?url=https://simkl.in/poster_no_pic_c.png

SIMKL_IMG_BASE = 'https://wsrv.nl/?url=https://simkl.in'

def image_url(path, kind='posters', size='_w', ext='.webp'):
    if not path:
        if kind != 'posters':
            return None  # no placeholder for fanart/episode/avatar
        ph = '_s' if size == '_s' else '_c'
        return f'{SIMKL_IMG_BASE}/poster_no_pic{ph}.png'
    return f'{SIMKL_IMG_BASE}/{kind}/{path}{size}{ext}&q=90'

enum SimklImage {
    static let imgBase = "https://wsrv.nl/?url=https://simkl.in"

    static func url(path: String?, kind: String = "posters",
                    size: String = "_w", ext: String = ".webp") -> String? {
        guard let p = path, !p.isEmpty else {
            guard kind == "posters" else { return nil }
            let ph = size == "_s" ? "_s" : "_c"
            return "\(imgBase)/poster_no_pic\(ph).png"
        }
        return "\(imgBase)/\(kind)/\(p)\(size)\(ext)&q=90"
    }
}

object SimklImage {
    private const val IMG_BASE = "https://wsrv.nl/?url=https://simkl.in"

    fun url(path: String?, kind: String = "posters",
            size: String = "_w", ext: String = ".webp"): String? {
        if (path.isNullOrEmpty()) {
            if (kind != "posters") return null
            val ph = if (size == "_s") "_s" else "_c"
            return "$IMG_BASE/poster_no_pic$ph.png"
        }
        return "$IMG_BASE/$kind/$path$size$ext&q=90"
    }
}

package simklimg

import "fmt"

const imgBase = "https://wsrv.nl/?url=https://simkl.in"

func URL(path, kind, size, ext string) string {
    if path == "" {
        if kind != "posters" {
            return ""
        }
        ph := "_c"
        if size == "_s" {
            ph = "_s"
        }
        return fmt.Sprintf("%s/poster_no_pic%s.png", imgBase, ph)
    }
    return fmt.Sprintf("%s/%s/%s%s%s&q=90", imgBase, kind, path, size, ext)
}

Generate a <img srcset> so the browser picks the right size for the user’s screen. The src falls back to the wsrv-proxied placeholder when poster is null.

<img
  src="https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_c.webp&q=90"
  srcset="
    https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_s.webp&q=90   40w,
    https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_cm.webp&q=90  84w,
    https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_c.webp&q=90  170w,
    https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_ca.webp&q=90 190w,
    https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_m.webp&q=90  340w
  "
  sizes="(max-width: 480px) 170px, 190px"
  width="170" height="250" loading="lazy"
  onerror="this.onerror=null;this.src='https://wsrv.nl/?url=https://simkl.in/poster_no_pic_c.png';this.removeAttribute('srcset');"
  alt="Poster"
/>

Always set explicit width / height so the browser reserves layout space and avoids cumulative layout shift (CLS).

A component with built-in fallback and onError recovery for stale paths.

import { useState } from 'react';

const SIMKL_IMG_BASE = 'https://wsrv.nl/?url=https://simkl.in';
const PLACEHOLDER = `${SIMKL_IMG_BASE}/poster_no_pic_c.png`;

export function Poster({ path, size = '_c', alt = '' }) {
  const initial = path ? `${SIMKL_IMG_BASE}/posters/${path}${size}.webp&q=90` : PLACEHOLDER;
  const [src, setSrc] = useState(initial);
  return (
    <img
      src={src}
      alt={alt}
      width="170"
      height="250"
      loading="lazy"
      onError={() => setSrc(PLACEHOLDER)}
    />
  );
}

onError falls back if the image 404s for any reason (e.g. the title was merged and the path is stale).

Show a tiny _s48 fanart thumbnail upscaled with a CSS blur, then swap in the full image when loaded. Fanart has no placeholder — if path is null, render nothing.

import { useState } from 'react';

const SIMKL_IMG_BASE = 'https://wsrv.nl/?url=https://simkl.in';

export function Fanart({ path }) {
  const [loaded, setLoaded] = useState(false);
  if (!path) return null;

  const tiny = `${SIMKL_IMG_BASE}/fanart/${path}_s48.webp&q=90`;
  const full = `${SIMKL_IMG_BASE}/fanart/${path}_medium.webp&q=90`;

  return (
    <div style={{ position: 'relative' }}>
      <img src={tiny} alt="" aria-hidden
        style={{
          filter: 'blur(20px)', transform: 'scale(1.1)',
          width: '100%', position: 'absolute', inset: 0,
        }}
      />
      <img src={full} alt="" onLoad={() => setLoaded(true)}
        style={{
          width: '100%', opacity: loaded ? 1 : 0,
          transition: 'opacity 300ms', position: 'relative',
        }}
      />
    </div>
  );
}

Use a remote placeholder URL or a bundled image — both work.

import SDWebImage

let url = SimklImage.url(path: poster, kind: "posters", size: "_c")
    .flatMap(URL.init(string:))
let placeholderURL = URL(string: "https://wsrv.nl/?url=https://simkl.in/poster_no_pic_c.png")!

imageView.sd_setImage(with: url, placeholderImage: nil) { image, _, _, _ in
    if image == nil {
        imageView.sd_setImage(with: placeholderURL)
    }
}

Or with Kingfisher:

import Kingfisher

let url = SimklImage.url(path: poster, kind: "posters", size: "_c")
    .flatMap(URL.init(string:))

imageView.kf.setImage(
    with: url,
    options: [
        .onFailureImage(UIImage(named: "poster_placeholder")),
        // …or fetch the wsrv placeholder remotely:
        // .alternativeSources([.network(URL(string:
        //     "https://wsrv.nl/?url=https://simkl.in/poster_no_pic_c.png")!)])
    ]
)

Loading via Coil on Android Compose, with the wsrv-proxied placeholder used both as placeholder and error:

import coil.compose.AsyncImage
import coil.request.ImageRequest

AsyncImage(
    model = ImageRequest.Builder(LocalContext.current)
        .data(SimklImage.url(path = poster, size = "_c"))
        .crossfade(true)
        .build(),
    contentDescription = title,
    placeholder = rememberAsyncImagePainter(
        "https://wsrv.nl/?url=https://simkl.in/poster_no_pic_c.png"
    ),
    error = rememberAsyncImagePainter(
        "https://wsrv.nl/?url=https://simkl.in/poster_no_pic_c.png"
    ),
    contentScale = ContentScale.Crop,
    modifier = Modifier.size(width = 170.dp, height = 250.dp),
)

Posters

Six sizes, ranging from cinematic landscape (_w) down to a 40-pixel sliver (_s).

Previews
Reference table

_w — 600 × 338, landscape, cropped

_m — 340 × *, medium portrait

_ca — 190 × 279 (or 285), card aspect

_c — 170 × 250 (or 256), compact card

_cm — 84 × 124, card mini

_s — 40 × 57, smallest thumbnail

Suffix	Size	File size	Notes	Example
`_w`	600 × 338	~41 KB	Landscape, cropped. Hero/header banners.	View
`_m`	340 × *	~49 KB	Medium portrait. Detail screens.	View
`_ca`	190 × 279 (or 285)	~21 KB	Card aspect. Grids.	View
`_c`	170 × 250 (or 256)	~18 KB	Compact card. Lists.	View
`_cm`	84 × 124	~5.7 KB	Card mini. Dense lists.	View
`_s`	40 × 57	~1.6 KB	Smallest. Inline / autocomplete.	View

Widths are exact. Heights are the common cases, not guarantees. Poster height follows the source image and varies per title. See Poster height is not fixed.

Choosing a size for high-DPI screens

The Notes column above suggests a size by layout slot. That assumes a 1x display. Phones run at 2x or 3x, and most laptop screens are 2x, so a _c poster in a 170px slot gets upscaled by the browser and looks soft. The rule: multiply your CSS slot width by the device pixel ratio, then pick the smallest suffix whose width is greater than or equal to that number. Poster widths are _s 40, _cm 84, _c 170, _ca 190, _m 340.

CSS slot width	1x	2x	3x
40 px	`_s`	`_cm`	`_c`
60 px	`_cm`	`_c`	`_ca`
84 px	`_cm`	`_c`	`_m`
100 px	`_c`	`_m`	`_m`
113 px	`_c`	`_m`	`_m`
170 px	`_c`	`_m`	`_m`
190 px	`_ca`	`_m`	`_m`

The practical takeaway: any poster rendered at up to roughly 170 CSS pixels should use _m on a high-DPI screen, not _c. _m at 340px covers a 113px slot at 3x and a 170px slot at 2x. That covers the common phone case, so _m is a sensible default for mobile poster art. It is also the largest portrait poster, so above those widths you are already at the ceiling. _w is not an alternative here, it is a 600 × 338 landscape crop for banners.

No poster size has a guaranteed height, and _m is the loosest of all._m is a width-only resize to 340px. It never crops, so its height is purely whatever the source aspect ratio gives. That is why the table lists it as 340 × *. Measured across 30 trending titles, _m came back between 480px and 513px tall._c, _ca, _cm and _s are also width-first, but each caps the height at its listed maximum. Titles under the cap keep their own aspect ratio, titles over it are centre-cropped vertically. Their heights vary too, just in a narrower band: the same 30 titles returned _c at 241, 250, 255 and 256 pixels tall. _w is the one true fixed size, always 600 × 338.The consequence: if your layout constrains only one dimension, for example an img with a width but no height, or a fixed-height grid cell, your rows will change size per title. This is already true today with _c. Switching to _m makes it obvious, because the height spread is wider.Pin both dimensions (or set aspect-ratio) and add object-fit: cover. For background images use background-size: cover. That reproduces the same centre-crop the capped sizes do server-side, so the result is visually identical to _c, just at higher resolution.

/* Same visual result as _c, sharper on 2x and 3x screens. */
.poster {
  width: 170px;
  height: 250px;          /* or: aspect-ratio: 170 / 250; */
  object-fit: cover;
  object-position: center;
}

For a background image:

.poster-bg {
  width: 170px;
  aspect-ratio: 170 / 250;
  background-image: url("https://wsrv.nl/?url=https://simkl.in/posters/74/74415673dcdc9cdd_m.webp&q=90");
  background-size: cover;
  background-position: center;
}

Let users cap image quality on mobile

Defaulting to _m on phones triples the bytes per poster versus _c. On a metered connection that is a real cost, so make it a user choice rather than a hard default. Ship a setting with three options: full quality, reduce on cellular only, and always reduce. “Reduce” means step down one suffix, so _m becomes _c and _c becomes _cm. Default to reducing on cellular. Also respect the OS-level signal, which users set once and expect every app to honour:

Platform	Signal
iOS	Low Data Mode. Check `allowsConstrainedNetworkAccess` on your `URLSessionConfiguration`, or watch `NWPath.isConstrained`.
Android	Data Saver. Check `ConnectivityManager.getRestrictBackgroundStatus()`.
Web	`navigator.connection.saveData`, plus `effectiveType` for a rough speed hint.

Cache each size under its own key so toggling the setting does not evict the images the user already has. See Caching.

Fanart

Wide background art — the cinematic still you typically use behind the title on a detail screen.

Previews
Reference table

`_d.jpg` — original size, darker, smaller filesize. JPG only — the one fanart size that isn't `.webp`.

Suffix	Size	File size	Notes	Example
`_medium`	1920 × 1080	~357 KB	Full HD. Detail-screen hero.	View
`_mobile`	960 × 540	~96 KB	Mobile-optimized hero.	View
`_w`	600 × 338	~29 KB	Card-friendly.	View
`_d`	original	~103 KB	Darker, smaller filesize. JPG only — the one fanart size that isn’t `.webp`.	View
`_s48`	48 × 27	~1 KB	Tiny placeholder for blur-up effects.	View

Episodes

Previews
Reference table

Suffix	Size	File size	Example
`_w`	600 × 338	~29 KB	View
`_c`	210 × 118	~8 KB	View
`_m`	112 × 63	~3 KB	View

Avatars

Previews
Reference table

_24 — 24 × 24

_100 — 100 × 100

(none) — 200 × 200

_256 — 256 × 256

_512 — 512 × 512

Suffix	Size	File size	Example
`_24`	24 × 24	~0.7 KB	View
`_100`	100 × 100	~5.6 KB	View
(none)	200 × 200	~17 KB	View
`_256`	256 × 256	~26 KB	View
`_512`	512 × 512	~79 KB	View

Avatars are JPG-only and served directly from simkl.in (no wsrv.nl proxy needed for these — they’re already small).

Fallback when images are missing

When a poster, fanart, or episode field is null (or the path is empty), use these built-in placeholders. They live at the root of simkl.in and are served through wsrv.nl just like the other images:

default placeholder — default — full size

URL	Use for	File size	Example
`https://wsrv.nl/?url=https://simkl.in/poster_no_pic.png`	Default — full-size missing-poster	~25 KB	View
`https://wsrv.nl/?url=https://simkl.in/poster_no_pic_c.png`	Match `_c` posters (170 × 250)	~9 KB	View
`https://wsrv.nl/?url=https://simkl.in/poster_no_pic_c_grey.png`	Match `_c` with a softer grey tone	~24 KB	View
`https://wsrv.nl/?url=https://simkl.in/poster_no_pic_s.png`	Match `_s` posters (40 × 57)	~1.7 KB	View

Fanart has no dedicated placeholder. When fanart is null, hide the fanart element rather than showing a broken/empty image — most apps render a solid color or use the poster’s blurred-up _s48 thumbnail behind a tint instead.

Caching

Cache images by URL forever. The image at a given URL never changes — once you’ve downloaded it, don’t fetch it again. Re-downloading wastes your users’ bandwidth and ours.

Get started

Authentication

Conventions

Guides

API Debug

Resources

Anatomy of a URL

Code samples

Posters

Choosing a size for high-DPI screens

Let users cap image quality on mobile

Fanart

Episodes

Avatars

Fallback when images are missing

Caching

​Anatomy of a URL

​Code samples

​Posters

​Choosing a size for high-DPI screens

​Let users cap image quality on mobile

​Fanart

​Episodes

​Avatars

​Fallback when images are missing

​Caching

Anatomy of a URL

Code samples

Posters

Choosing a size for high-DPI screens

Let users cap image quality on mobile

Fanart

Episodes

Avatars

Fallback when images are missing

Caching