You can get a free API key by:

1. Visiting the registration page
2. Creating an account with your email and username
3. Accessing your dashboard to view your API key

The Free plan includes 10,000 requests per month. Upgrade to Pro or Premium for more features and higher limits.

TOP Posters offers three plans to suit different needs:

• Free: 10,000 requests/month. Posters and 16:9 banners with ready-to-use settings, English artwork, the three default ratings (IMDb, Metacritic, Rotten Tomatoes) and your choice of poster style.
• Pro: 30,000 requests/month. Full control over posters and banners: 25+ rating sources, 35+ artwork languages, artwork source and resolution, badge layout, trend indicators, technical information badges and per-device settings.
• Premium: 50,000 requests/month. Everything in Pro, plus episode thumbnails, transparent title logos and cinematic backgrounds.

Pro and Premium come with a 7-day free trial, and both can add Double Monthly Requests if you need more API calls. Compare every feature on the pricing page.

Your monthly allowance runs on a 30-day window, and the API Key tab shows how many requests you have used and when the counter resets. Once the limit is reached, the API stops generating artwork until the reset, and integrations that support it fall back to the original artwork. If you regularly need more, upgrade your plan or add Double Monthly Requests.

When a Pro or Premium subscription expires, the key keeps its plan so you can renew it without changing anything in your apps, but it stops serving artwork. To keep using TOP Posters for free, regenerate the key from the API Key tab: it returns to the Free plan, your settings reset to the Free defaults, and you must paste the new key into your integrations.

Four styles are available on every plan: TOP Posters, RPDB, WaterDrop and Minimal. Choose one in the Poster Settings tab.

Minimal shows a single rating. On the Free plan it is always IMDb; on Pro and Premium it is the first available source in your configured rating order.

Yes — all customisation happens in your User Dashboard, with a tab for each type of artwork: Poster Settings, Banners, Backgrounds, Thumbnails and Logos. Changes apply to the API instantly; media players that store artwork, such as Plex and Jellyfin, show them after a metadata refresh.

The available options depend on your plan:

• Poster styles — TOP Posters, RPDB, WaterDrop and Minimal (every plan).
• Languages — Localized artwork in 35+ languages (Pro/Premium).
• Rating sources — Choose and order sources from 25+ available (Pro/Premium).
• Technical information badges — Resolution, HDR, audio format, country and age rating (Pro/Premium).
• Trend indicators — Show whether a title is trending up or down (Pro/Premium).
• Episode thumbnails, transparent logos and backgrounds — Premium.

A banner is 16:9 horizontal artwork with the title logo composited on it and rating badges on top — think of it as a landscape card rather than a vertical poster. Banners are available on every plan and are disabled by default: open the Banners tab to enable them. On the Free plan they are served with fixed settings — TMDB artwork at 720p and the three standard ratings (IMDb, Metacritic, Rotten Tomatoes) centered at the top in the small size, with the title logo on. Pro and Premium unlock artwork source, resolution, rating selection, badge position and size, and technical information.

The artwork is always textless when one exists, because the title comes from the logo. You choose where up to five rating badges go, while the logo is placed and sized automatically in the cleanest area of the image, avoiding faces and your badges. At the larger badge sizes fewer than five badges fit, and the extra ones are dropped from the end of your order.

Language follows Poster Settings, while the artwork source is a banner setting of its own.

Episode thumbnails are a Premium feature: rated episode stills for TV and anime, so the same visual style carries over from catalogs into season and episode browsing. Enable and configure them in the Thumbnails tab: badge style, layout, position and size, rating source and output resolution.

Turn on Force blur to blur every still and avoid spoilers while keeping the rating readable. Thumbnails work with the Stremio Addon Wrapper, Plex and the official Jellyfin plugin.

Backgrounds are a Premium-only, opt-in 16:9 surface for TV detail pages. In Dashboard → Backgrounds you can choose Editorial Rail, Glass Dossier or Minimal, either top corner, artwork source, resolution, and the exact information order.

Backgrounds prefer textless artwork, skip any missing information and use your Poster Settings language. The Addon Wrapper only replaces backgrounds that the original addon already provides.

Transparent title logos are a Premium-only feature and are disabled by default. Open the Logos tab, enable them, then choose an independent badge style and rating order.

The logo language, artwork source and resolution follow Poster Settings.

Yes. On Pro and Premium, the Devices tab lets you customise poster, banner and thumbnail settings for each device or client — for example a different badge position on your TV than on your phone.

A device appears in the list after it makes an artwork request that identifies it. The Addon Wrapper and the AIOMetadata patterns in the URL Patterns section do this automatically.

Every artwork endpoint accepts two optional query parameters:

• fallback_url — the original artwork. When TOP Posters cannot serve an image (the feature is disabled, unavailable on the plan, or there is no artwork for the title), the API answers with an HTTP 307 redirect to this URL instead of an error, so your users never see a broken image.
• user_agent — a stable identifier for the requesting device, used to apply per-device settings from the Devices tab. Without it, the request's User-Agent header is used.

See the API documentation for every endpoint and parameter.

We're here to help! You can reach us through:

• Discord: Join our community
• Email: [email protected]

How it works:

1. Go to the Addon Wrapper tab in your dashboard
2. Import your existing Stremio addons by pasting their manifest URLs
3. Install the generated personal wrapper URL in Stremio (one click)
4. All catalogs from your imported addons will now display TOP Posters artwork, based on your plan and settings

Alternative — direct integration via compatible addons
If you prefer not to use the Wrapper, you can configure TOP Posters directly in a compatible Stremio addon such as AIOMetadata. Follow the AIOMetadata setup FAQ below and copy the ready-to-paste patterns from the URL Patterns section of your dashboard. Note that this approach only covers the specific addon and does not apply TOP Posters across all your catalogs.

1. In AIOMetadata, enter your TOP Posters API key in Integrations.
2. Open Art Providers → Art URL Overrides and choose Custom Art URLs.
3. Copy the AIOMetadata patterns from your dashboard's URL Patterns section and paste each one into its matching field.
4. Leave Landscape URL Pattern empty so the poster pattern also supplies landscape artwork.
5. Enable Proxy Rating & Custom Art to recover the original artwork when a request fails, then save.

Keep the placeholders unchanged: AIOMetadata replaces {top_key} with your TOP Posters API key, {shape} with the requested poster shape and {user_agent} with the requesting device's user agent.

Language and style follow your TOP Posters dashboard settings. The available artwork patterns depend on your plan.

Alternative — manual addon order configuration

If you are using a compatible addon directly (without the Wrapper), episode thumbnails require a specific addon order in Stremio:

1. Find a metadata addon that supports thumbnails (e.g., AIOMetadata)
2. Configure it with your TOP Posters API key, save and install in Stremio
3. In your addon list, move the metadata addon to the top (it must be first)
4. Thumbnails will now be provided by that addon across all content in Stremio

Yes. Open the Addon Wrapper and choose Poster or Banner on each catalog card; you can also apply one choice to every catalog at once. Stremio has no dedicated banner field, so a horizontal card is sent as a poster declared as landscape. Nuvio also receives its own banner field.

The per-catalog choices are saved even while banners are globally disabled, but posters remain active until you enable banners in the Banners tab. Titles without horizontal artwork fall back to the original poster from the upstream addon.

If episode thumbnails aren't appearing, check the following:

1. API Tier: Episode thumbnails require a Premium plan. Check your tier on the API Key tab
2. Thumbnails enabled: Make sure episode thumbnails are enabled in your Thumbnails tab
3. Content Type: Thumbnails are only available for TV series, not movies
4. Using the Wrapper? If yes, verify your addons are correctly imported in the Addon Wrapper
5. Using a direct addon? Make sure it is positioned first in your Stremio addon list and the API key is entered correctly

Different devices and clients have different UI layouts. The badge may be rendered behind Stremio's UI elements on some screens.

Solution: Configure the badge position per device from your dashboard:

1. Go to the Thumbnails tab to set the default badge position
2. For per-device overrides, use the Devices tab — each device/client that has made a thumbnail request will appear here with its own position and size settings
3. Try different positions (top-left, top-right, bottom-left, bottom-right) to find what works best on that device

The device settings let you fine-tune the badge for each device independently.

Alternative — external addon manager
If you are managing addons directly in Stremio without the Wrapper, you can reorder them using stremio-addon-manager.vercel.app. Keep in mind that for full TOP Posters API support across all your addons, the Wrapper is strongly recommended.

How it works:

1. Open xperience-app.com and build your Nuvio setup
2. In Settings → Poster providers, select Top Posters and enter the API key from your dashboard
3. Drag Top Posters to the top of the list so it becomes your primary provider
4. Install the generated setup in Nuvio

Alternative — custom URL pattern
Nuvio also accepts a custom artwork URL pattern. Copy your personal Nuvio pattern, with your API key already included, from the URL Patterns section of your dashboard. In Nuvio, open Settings → Layout → Poster Card Style → Custom Poster Source. Use Configure via Phone to paste the pattern. One pattern covers portrait posters and landscape cards, which are served as banners with your Banner settings. Note that this approach is limited to posters and banners.

TOP Posters integrates with Plex as a native Metadata Provider — a feature built into Plex Media Server that lets you connect external sources for artwork and metadata.

Once configured, TOP Posters becomes the primary metadata agent for your Movie and TV libraries. This means:

• Your media posters and thumbnails will come from the TOP Posters API and will display multi-source rating badges from various platforms
• The standard Plex agent fills in anything that's missing (title, synopsis, genres, cast...)

First, copy your personal Movies provider URL. Replace {YOUR_API_KEY} with the API key shown in your dashboard:

The process for TV Shows is identical. Copy your personal TV provider URL:

Now that the providers are configured, you need to refresh metadata so Plex fetches the new posters.

To refresh an entire library:

1. Go to Settings → Libraries
2. Hover over a library, click the three dots (⋯) icon
3. Select Refresh All Metadata

To refresh a single item:

1. Open any movie or TV show page in Plex Web
2. Click the three dots (⋯) button (next to Play)
3. Select Refresh Metadata

If the agent you created doesn't appear in the library's Advanced settings dropdown:

• Refresh the page — Plex sometimes needs a browser refresh to show newly created agents
• Check the provider URL — Go back to Settings → Metadata Agents → Metadata Providers and verify the URL was saved correctly. Make sure your API key is in the URL and has no typos
• Verify your API key — Check that your key is active on your dashboard
• Check the library type — The Movies agent only appears for Movie libraries, and the TV Shows agent only appears for TV Show libraries. Make sure you're editing the correct library type

If posters haven't changed after a metadata refresh, try the following:

• Force a full refresh: Open a movie page → three dots → Fix Incorrect Match, search for the title, and confirm the match. This forces Plex to fetch fresh metadata from your provider
• Check Plex logs: In Plex Web, go to Settings → Troubleshooting → Download Logs and look for any errors related to your provider URL
• Test the URL manually: Open your provider URL directly in a browser (e.g. https://api.top-posters.com/{YOUR_API_KEY}/plex/movie). You should see a JSON response with a MediaProvider object. If you get an error, your API key may be invalid or expired
• Plex poster lock: If you manually set a poster for an item before, Plex may have locked it. Open the item → three dots → View Info → Poster tab → select the TOP Posters poster

In Plex, Technical Specs badges (showing resolution, audio format and HDR standard) work differently from Stremio. Instead of fetching specs from an external database, they are read directly from your media filenames.

This means that for a poster to show a specs badge, your file must include the relevant information in its name, following common naming conventions. For example:

• Movie.Title.2160p.DV.TrueHD.Atmos.mkv → 4K · Dolby Vision · Dolby Atmos
• Movie.Title.1080p.HDR10.DTS-HD.mkv → 1080p · HDR10 · DTS-HD MA
• Movie.Title.2160p.SDR.AAC.mkv → 4K · AAC

The following tags are recognised in filenames:

• Resolution: 2160p, 4K, UHD, 1080p, 720p
• HDR: DV, DoVi, HDR10+, HDR10, HDR, HLG
• Audio: TrueHD.Atmos, Atmos, DTS-X, DTS-HD.MA, DTS-HD, DTS, DD+, EAC3, AC3, AAC, FLAC

If none of these tags are found in the filename, no specs badge will be shown on that poster — even if the Technical Specs option is enabled in your dashboard.

Trend indicators (arrows showing if a movie is trending up or down) are a feature that highlights currently popular titles based on external lists.

Unlike Stremio, Plex does not use a list-based system for its library view. Since Plex is focused on your local media files rather than live-updating lists, it cannot correctly interpret the popularity metadata needed to display these indicators. Therefore, trend indicators are not available for Plex, even if enabled in your dashboard.

There are two ways to use TOP Posters with Jellyfin:

Check the TOP Posters plugin repository and Gelato repository for current Jellyfin compatibility before installing.

Add the official TOP Posters repository to your Jellyfin server:

1. Open the Jellyfin administration Dashboard
2. Go to Plugins → Repositories
3. Click +, enter a name such as TOP Posters, and paste the repository URL above
4. Save the repository and return to the plugin catalog

1. Open Dashboard → Plugins → Catalog and find TOP Posters in the Metadata category
2. Install the plugin and restart Jellyfin when prompted
3. Open the TOP Posters plugin settings, paste the API key from your dashboard, and save
4. Use the Poster Settings and Thumbnails tabs to customise artwork

1. Edit each relevant Jellyfin library and enable TOP Posters among the image fetchers for movies, series, and episodes
2. Move TOP Posters higher in the image fetcher priority when you want it selected first
3. For existing items, run Refresh Metadata and select the option to replace existing images

Gelato integrates Stremio-powered search, catalogs, and streams into Jellyfin and currently supports AIOStreams as its Stremio source.

1. Create or edit your AIOStreams manifest
2. In AIOStreams, open the poster service settings and select TOP Posters
3. Enter your TOP Posters API key
4. Enable Use Poster Service for Library/Continue Watching if you want TOP Posters applied to individual library items
5. Connect the saved AIOStreams manifest to Gelato, then restart Jellyfin after changing the AIOStreams manifest or configuration

Resources: Gelato, Gelato starter guide, and AIOStreams.

• Confirm the plugin is installed and enabled in Dashboard → Plugins
• Restart Jellyfin after installing or updating the plugin
• Verify that your Jellyfin version is supported by the latest plugin release on GitHub
• Check the Jellyfin server logs for plugin loading errors

• Verify that TOP Posters is enabled and prioritised in the library's image fetcher settings
• Run Refresh Metadata with image replacement enabled; a normal library scan may keep existing artwork
• Confirm the item has a TMDB or IMDb provider ID
• Confirm the API key saved in the plugin is active on your dashboard

• Episode thumbnails require the official TOP Posters plugin; Gelato + AIOStreams only applies posters
• Confirm your TOP Posters account has a Premium plan
• Enable episode thumbnails in your Thumbnails settings
• Confirm the series has a TMDB or IMDb provider ID and the episode has valid season and episode numbers
• Refresh the episode metadata with image replacement enabled

The official TOP Posters plugin is an image provider for your native Jellyfin libraries. It is the recommended choice when you want rated posters and episode thumbnails without changing how your library content is sourced.

Gelato connects Jellyfin to AIOStreams so Stremio search results, catalogs, and streams behave like Jellyfin items. AIOStreams can apply TOP Posters to posters, but not to episode thumbnails.

All artwork preferences are managed from your TOP Posters dashboard and applied automatically through your API key:

• Use Poster Settings for language, badge sources, styles, and poster options
• Use Thumbnails for episode badge position, size, layout, and source
• Refresh the affected artwork in Jellyfin after changing settings so cached images are replaced

We're actively working on integrations for more platforms. Currently supported:

• Stremio — via the TOP Posters Addon Wrapper (see the Stremio section above)
• Nuvio — via Xperience or a custom URL pattern (see the Nuvio section above)
• Plex — via the native Metadata Provider (see the Plex section above)
• Jellyfin — via the official TOP Posters plugin (see the Jellyfin section above)

If you'd like to request support for a specific platform, reach out via email or our Discord community.