XRDB provides three main image endpoints. Poster, backdrop, and logo artwork uses GET /{type}/{id}.jpg. Episode thumbnails use GET /thumbnail/{id}/S{season}E{episode}.jpg.

GET /poster/tt0133093.jpg?ratings=imdb,tmdb&lang=en
GET /backdrop/tmdb:movie:603.jpg?ratings=mdblist&style=plain
GET /logo/tmdb:tv:1399.jpg
GET /thumbnail/xrdbid:tt0944947/S01E01.jpg?thumbnailRatings=tmdb,imdb

Poster and backdrop responses return JPEG. Logo requests keep the .jpg route but may return PNG when transparency is preserved.

The Media ID field accepts a base title ID for posters, backdrops, and logos. Thumbnail previews need an episode target. Use this guide to match the field input, the exported route, and the most common scoped query params.

Accepted base ID families

• IMDb — best general base ID for posters and simple movie or show lookups. Examples: tt0133093, tt0944947
• Typed TMDB — best when movie and TV type must stay explicit. Required by Strict TMDB scope for backdrop and logo requests. Examples: tmdb:movie:603, tmdb:tv:1399
• XRDB canon ID — keeps an IMDb base ID explicit in proxy and episodic workflows. Examples: xrdbid:tt0944947
• TVDB — supported for series and episode targeting when your upstream IDs come from TVDB. Examples: tvdb:121361
• Anime IDs — use the native anime provider ID when your source does not begin with IMDb or TMDB. Examples: anilist:16498, mal:16498, anidb:5114, kitsu:7442

Input format by type

• Poster input — baseId. Example: tt0133093 or tmdb:movie:603
• Backdrop input — baseId. Example: tmdb:tv:1399 or xrdbid:tt0944947
• Logo input — baseId. Example: tmdb:movie:603 or tmdb:tv:1399
• Thumbnail input — seriesId:season:episode. Example: tt0944947:1:1 or tmdb:tv:1399:1:1
• Kitsu thumbnail input — seriesId:episode. Example: kitsu:7442:1

Strict TMDB and route safety

If you enable Strict TMDB scope, backdrop and logo requests must stay typed as tmdb:movie:603 or tmdb:tv:1399. Plain tmdb:603 is ambiguous and will be rejected. Poster routes can stay on IMDb or another supported base ID when that fits your source better. The export panels show the full scoped query string XRDB will generate for your current workspace.

High signal query params

• idSource=tmdb — pins poster, backdrop, and logo exports to typed TMDB route patterns
• tmdbIdScope=strict — requires tmdb:movie:id or tmdb:tv:id for backdrop and logo requests
• thumbnailEpisodeArtwork=still|series — controls whether thumbnails prefer the episode still or the series backdrop source
• tmdb_ep_order=tvdb|tmdb — when set to tvdb, resolves episode coordinates through TVDB aired order before fetching the TMDB episode still; default is tmdb
• thumbnailRatings=tmdb,imdb — chooses the thumbnail specific rating providers without affecting poster, backdrop, or logo routes

Poster sources support tmdb, fanart, cinemeta, omdb, and random. Backdrop and logo sources support tmdb, fanart, cinemeta, and random.

fanart uses fanart.tv artwork when a fanart key is present and now honors textless poster and backdrop choices when Fanart exposes neutral language metadata. cinemeta uses MetaHub when an IMDb ID is available. omdb (poster only) uses the server OMDb key. clean, textless, and random textless poster filters only use sources that actually supply textless artwork, so unsupported providers are skipped automatically. random picks a seeded source across available candidates. blackbar renders a solid black strip instead of a real image.

Six rating presentation modes are available:

• Standard — individual provider badges
• Compact average — one compact aggregate badge
• Labeled average — aggregate with a label
• Critics + Audience — separate critic and audience aggregates
• Blockbuster — premium variant
• None — disables ratings entirely

Badge styles (glass, square, plain, stacked, media, silver) control the visual treatment. Glass is the default for posters and backdrops; plain is the default for logos.

Rating providers are specified via comma separated lists in ratings, posterRatings, backdropRatings, thumbnailRatings, or logoRatings query parameters.

Available providers include tmdb, mdblist, imdb, allocine, allocinepress, tomatoes, tomatoesaudience, letterboxd, metacritic, metacriticuser, trakt, simkl, rogerebert, myanimelist, anilist, and kitsu.

The default is all, which includes every configured provider. Specifying a custom list renders only those providers in the order listed.

Metadata translation changes text in proxied addon metadata (titles, descriptions, episode text) without affecting artwork rendering.

Four merge modes are available:

• Fill missing — safest, replaces only blanks or placeholders
• Prefer source — keeps addon text, fills gaps only
• Prefer requested language — replaces when an exact language match exists in TMDB
• Prefer TMDB — uses TMDB text whenever available

Anime gets extra fallback help using anime mapping plus AniList and Kitsu data when TMDB is missing text.

The XRDB proxy acts as a transparent overlay for any Stremio addon, replacing poster, backdrop, and logo images with XRDB generated versions while optionally translating metadata.

The proxy uses a base64url encoded config string (/proxy/{config}/manifest.json) generated by the configurator. That string encapsulates the base URL, API keys, per type style and layout settings, and optional overrides.

AIOMetadata exports generate URL patterns for custom art override fields in AIOMetadata compatible addons. Per type URL patterns (poster, backdrop, thumbnail, logo) are emitted with unchanged defaults omitted to keep patterns lean and type scoped.

The Hide credentials toggle masks patterns with placeholders without affecting live XRDB URLs. The Poster ID source selector controls whether poster URLs use auto mode (typed TMDB IDs), explicit TMDB, or IMDb IDs.

XRDB is stateless: it does not permanently store API keys on the server. Keys are read from incoming requests, letting public instances scale without shared API usage costs.

Keys are embedded directly into generated URLs (tmdbKey=...&mdblistKey=...&fanartKey=...) or addon proxy configurations and stored locally in localStorage when using the configurator.

Optional server side client IDs (XRDB_MAL_CLIENT_ID, XRDB_TRAKT_CLIENT_ID, XRDB_SIMKL_CLIENT_ID) extend ratings beyond BYOK. User supplied parameters always take precedence.

Each type (poster, backdrop, thumbnail, logo) has independent settings for rating providers, rating style, presentation, layout, badge sizing, artwork source, and quality badge limits.

Rating badge scale is type scoped for every artwork type, and the configurator now supports the same 70 to 200 range across poster, backdrop, thumbnail, and logo outputs.

Posters use posterRatingsLayout (top, bottom, left, right, and combinations). Backdrops use backdropRatingsLayout (center, right, right vertical) and can enable backdropBottomRatingsRow. The Quality Badges panel exposes poster placement controls for supported poster layouts, disables shared placement when certification is the only visible quality badge, adds a dedicated age rating position control for the active poster layout, and includes bulk enable and hide actions for visible quality badges.

Slider based customisation controls snap back to their defaults when you move close to the baseline and show a Default readout, while keeping keys, manifest inputs, and the current target unchanged.

Thumbnails are the most distinct: they use the /thumbnail/ route with dedicated episode artwork mode (still or series), their own rating provider list, and separate layout and sizing controls.

Get help with XRDB, ratings, proxy setup, or addon configuration through the community Discord servers.

You can also reach the developer directly at @ibbys89 on Discord.

XRDB RepoSupport