Frequently Asked Questions

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

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

TOP Posters offers three tiers to suit different needs:

• Free: 10,000 requests/month, basic rating sources (IMDb, Metacritic, RT), English posters only.
• Pro: 30,000+ requests/month, 25+ rating sources, full style customization, all 35+ languages, trend indicators, and technical specs banners.
• Premium: All Pro features plus Episode Thumbnails with ratings for TV shows.

You can compare all features and upgrade your plan on the pricing page.

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 posters and thumbnails with rating badges, based on your API tier

Alternative — direct integration via compatible addons
If you prefer not to use the Wrapper, you can configure your API key directly in any compatible Stremio addon (e.g. AIOMetadata). Open the addon configuration page, enter your TOP Posters API key in the designated field, save and install. Note that this approach only covers the specific addon and does not provide full API support across all your catalogs. You can find a list of compatible addons on the homepage.

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

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 User Agents 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 user agent 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.

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

Yes — all customisation for both Posters and Episode Thumbnails happens directly in your User Dashboard. Changes are applied instantly to the API and will appear on your media player after a metadata refresh.

The available options depend on your API Tier:

• Badge Customisation — Choose visual styles and positions (Pro/Premium).
• Languages — Get localized artwork in 35+ languages (Pro/Premium).
• Rating Sources — Select which sources to display from 25+ available (Pro/Premium).
• Technical Specs — Add banners for 4K, HDR, etc. (Pro/Premium).
• Episode Thumbnails — Full configuration for TV show thumbnails (Premium).

Free tier users get the default style with IMDb, Metacritic, and Rotten Tomatoes in English.

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 compatible addons (see the Stremio 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.