Images - Simkl API

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

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

Fanart

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

Previews
Reference table

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:

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.

​Anatomy of a URL

​Code samples

​Posters

​Fanart

​Episodes

​Avatars

​Fallback when images are missing

​Caching

Anatomy of a URL

Code samples

Posters

Fanart

Episodes

Avatars

Fallback when images are missing

Caching