How posters render

Understanding the render lifecycle explains why a brand-new title may show its plain poster at first, and how to read the response headers.

The default poster

poster-default (with no styling parameters) produces a clean, opinionated look that matches openposterdb.com:

• Bottom rating strip — a tidy badge strip along the bottom of the poster, laid out three per row, medium-sized, using each source’s official provider logo (label_style=o). No dark box or oversized glyphs.
• Dynamic Rotten Tomatoes icons — Rotten Tomatoes badges pick the right Tomatometer glyph automatically from the score: certified-fresh (critic ≥ 75 with enough reviews), fresh or rotten for the critic score, and upright / spilled / verified-hot for the audience score.
• Top-right award statuette — if the title won an Oscar (movies) or Emmy (TV), an icon-only statuette sits in the top-right corner, with no count or number. This is our scraped differentiator — RPDB has no award badges — and it is rendered automatically; it is not part of the bottom ratings row and is never affected by ratings_order / ratings_limit.

Every MDBList rating source (IMDb, TMDB, Rotten Tomatoes critic & audience, Metacritic, Trakt, Letterboxd, MyAnimeList, MDBList score, Roger Ebert) can be requested in the bottom strip on any key. You only need parameters to deviate from this default.

A poster request, step by step

1. Cache hit. If a rendered poster is already cached, you get it immediately (X-Cache-Status: HIT, cached for 24h).
2. Cache miss. On a miss, aioratings:
   • kicks off a render in the background — but only once the title actually has at least one scraped rating (IMDb / Rotten Tomatoes / Metacritic / Letterboxd), and
   • falls back to the plain source poster (the unrated artwork) for that request, so you always get an image (X-Cache-Status: MISS-FALLBACK).
3. Next request. Once the render finishes, the next request returns the rated and badged poster.

So a title you have never requested before may show its plain poster for the first view or two while ratings are scraped and the poster is rendered, then “upgrade” to the rated poster automatically. No action needed on your side.

Response headers worth knowing

Header	Meaning
X-Cache-Status	HIT, MISS-FALLBACK, etc. — whether you got the cached render or the fallback.
X-Elements-Hash	Identifies the exact design that produced the image. The cache is keyed on this, so the same design always resolves to the same cached render.

Always-fallback (and ?fallback=true)

In RPDB, ?fallback=true tells the provider to return the plain poster instead of a 404 when it has no rated poster yet.

aioratings already always falls back to the source poster on a cache miss (step 2 above), so in practice you rarely get a hard 404 for a real title. An explicit ?fallback=true flag — for strict RPDB parity — is accepted today.

Image bytes

Posters can be served as .jpg or .png. Historically the .jpg URL returned PNG bytes for cache compatibility; clients (Stremio, Plex, Kometa, Discord, Telegram, …) detect the real image format, so this is transparent. If you need guaranteed PNG bytes, request the .png extension.

Re-run to pick up the rated poster

Automated flows (the *arr webhook flow, a scheduled re-sync) should re-fetch a title later so a render that finished after the first fetch is picked up.