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://rpdb.aioratings.com

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

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 and gates rating sources, custom profiles and award badges. For sharing a URL without exposing your account credential, use the hashed key form h.{hash} in the {key} slot.

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

Endpoint families

Powered by a forked OpenPosterDB 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 (default) or .png to the id. .png is a distinct cache key and returns PNG bytes — useful for logos with transparency. See How posters render.

Tier gating, in short

Capability	Free	Premium / Pro
Rating sources	IMDb, Rotten Tomatoes, TMDB	+ Metacritic, Letterboxd
ratings_order / filtering	ignored (free source set)	honored
Custom profiles (non--default style)	no (403)	yes
Award badges	no	yes

Full detail in Plans & limits.