API overview

The aioratings API is an image API: every request returns an image (or a small JSON body for the validation endpoint). There is no SDK to install — you build a URL and fetch it.

Base URL

https://api.aioratings.com

This is the drop-in RPDB host. Requests use the path shape /{key}/{idType}/{style}/{id}.jpg.

Authentication

The API key sits in the first path segment, {key}. Your account tier (free / premium / pro) is read from the key on every request; it gates call volume and the custom canvas designer / saved profiles (premium-only) — not rating sources or the award statuette, which every tier gets. For sharing a URL without exposing your account credential, use the hashed key form h.{hash} in the {key} slot.

https://api.aioratings.com/YOUR_KEY/imdb/poster-default/tt0903747.jpg
https://api.aioratings.com/h.HASH/imdb/poster-default/tt0903747.jpg

Endpoint families

Powered by the aioratings render engine, aioratings exposes four artwork families plus a validity check:

Family	Style segment	Returns
Poster	poster-default (or a profile)	Rated/badged vertical poster (2:3).
Backdrop	backdrop-default	Wide backdrop / fanart (16:9).
Logo	logo-default	Title logo (clearlogo), transparent PNG.
Episode still	episode-default	Per-episode still frame.
Validity	isValid	JSON: key validity + usage.

See Endpoints for each one’s URL shape, and Query parameters for the full parameter surface that applies across them.

Image format

Append .jpg to the id for posters, backdrops and episode stills. (Logos are served as .png since a clearlogo needs transparency.) See How posters render.

Tier gating, in short

Capability	Free	Premium / Pro
Monthly image calls	10,000 / mo	unlimited (fair-use ~1,000,000 / mo)
Rating sources (all MDBList)	all	all
ratings_order / filtering	honored	honored
Award statuette (Oscar / Emmy)	yes	yes
Custom canvas designer + saved profiles	no (poster-default only; profile → 403)	yes

Full detail in Plans & limits.