Query parameters

All parameters are optional query-string values appended to any endpoint URL:

…/poster-default/tt0903747.jpg?imageSize=medium&ratings_order=imdb,rt&image_source=t

The default poster already looks great with no styling parameters at all — a clean bottom rating strip with official provider logos and dynamic Rotten Tomatoes icons (see How posters render). The parameters below are for fine-grained control.

Parameters are grouped below by what they control. Unknown parameters are accepted and ignored, so an RPDB client passing extra params still works.

Image size

`imageSize`

The rendered output size. Accepts named size tokens.

Value	Use
`small`	Compact (lists, mobile)
`medium`	Default poster size
`large`	Prominent / desktop grids
`very-large` (`verylarge`)	Full-resolution render

?imageSize=medium

Larger sizes are sharper but heavier. medium is a good poster default; large/very-large suit backdrops and hero artwork.

Rating selection

These control which rating badges appear and in what order. Every key — free, premium and pro — can choose from the full set of MDBList rating sources below; tiers differ in call volume and the custom canvas designer, not in which sources you can request (see Plans & limits).

`ratings_order`

Comma-separated source keys, in the order they should render in the bottom row.

?ratings_order=imdb,rt,mc,lb

All MDBList rating sources are available:

Key	Source
`imdb`	IMDb
`tmdb`	TMDB
`rt`	Rotten Tomatoes (critic)
`rta`	Rotten Tomatoes (audience)
`mc`	Metacritic
`trakt`	Trakt
`lb`	Letterboxd
`mal`	MyAnimeList
`mdblist`	MDBList score
`ebert`	Roger Ebert

Rotten Tomatoes (rt, rta) renders the engine’s dynamic Tomatometer icons — certified-fresh / fresh / rotten for critics, upright / spilled / verified-hot for audience — chosen automatically from the score.

The award sources oscar and emmy (our scraped differentiator — RPDB has neither) are not part of this bottom row. They render automatically as a top-right icon-only statuette for any title that won, with no count text. See How posters render.

`ratings_limit`

Maximum number of rating badges to show (after ordering).

?ratings_limit=2

`ratings_exclude`

Comma-separated source keys to omit. Applied after ratings_order.

?ratings_exclude=tmdb,lb

Badge styling

Control how each rating/award badge looks.

`badge_style`

How the badge group is laid out.

Value	Style
`h`	Horizontal — badges side by side (default)
`v`	Vertical — badges stacked
`d`	Diagonal

?badge_style=h

`badge_size`

Relative badge scale.

Value	Size
`xs`	Extra small
`s`	Small
`m`	Medium (default)
`l`	Large
`xl`	Extra large

?badge_size=l

`badge_shape`

Corner shape of badges.

Value	Shape
`r`	Rounded corners
`p`	Pill (fully rounded)

?badge_shape=p

`badge_background`

The badge background treatment.

Value	Background
`d`	Dark plate
`k`	Black plate
`t`	Tinted / brand plate
`n`	None — transparent (text + official logo only)

?badge_background=n

`label_style`

How each badge’s label is shown.

Value	Label
`o`	Official — source’s official logo lockup (default)
`t`	Text — the score/percentage value
`i`	Icon only — glyph/logo, no value

?label_style=o

Artwork source & variants

`image_source`

Which artwork provider to pull from. t = TMDB, f = Fanart.tv.

Value	Source
`t`	TMDB
`f`	Fanart.tv

?image_source=f

Fanart.tv is the better source for logos and textless/clean artwork; TMDB has the broadest poster coverage.

`lang`

Preferred artwork language as an ISO 639-1 code. Falls back to the title’s default when no localized artwork exists.

?lang=en
?lang=de

`textless`

Prefer a textless (clean, no-title) version of the artwork where one exists.

Value	Effect
`true`	Prefer textless artwork
`false`	Allow text/title artwork (default)

?textless=true

Layout & composition

How rating badges are placed and arranged on the artwork.

`position`

Where the ratings block sits on the image.

Value	Position
`tl` · `tc` · `tr`	Top: left · center · right
`l` · `r`	Side columns: left · right
`bl` · `bc` · `br`	Bottom: left · center · right (default `bc`)

?position=bl

`direction`

The badge stacking direction within the block.

Value	Direction
`horizontal`	Side by side
`vertical`	Stacked

?direction=horizontal

`split`

Split the badge group across two edges of the image (e.g. ratings on one side, award on the other).

Value	Effect
`true`	Distribute badges across opposite edges
`false`	Keep badges in one block (default)

?split=true

`edge_inset`

Padding (in pixels) between the badge block and the image edge.

?edge_inset=24

Image processing

`fit`

How the source artwork is fit to the output frame.

Value	Fit
`cover`	Fill the frame, cropping overflow (default)
`native`	Keep the source’s native aspect, no crop
`pad`	Fit entirely, padding any gaps
`blur`	Fit entirely, fill gaps with a blurred extension of the artwork

?fit=cover

`blur`

Apply a Gaussian blur to the artwork. Useful behind overlaid badges or for spoiler-free episode stills.

Value	Effect
`true`	Blur the artwork
`false`	No blur (default)

?blur=true

Compatibility

`fallback`

RPDB-compatible: return the plain source artwork instead of an error when no rated render exists yet.

Value	Effect
`true`	Serve the plain poster on a miss

?fallback=true

aioratings already always falls back on a cache miss, so this is mostly for strict RPDB parity. See How posters render.