Embed posters on your site

Quick start

Open any poster page, hit Share → Embed image, and paste the snippet into your HTML. That’s it — preview sizes need no registration, no API key, and have no usage limits.

<a href="https://movieposterdb.com/the-matrix-tt0133093/p/…">
  <img src="https://posters.movieposterdb.com/…/s_….jpg" alt="The Matrix poster" loading="lazy">
</a>

Always copy image URLs from the site (the share dialog, or right-click → copy image address). Poster paths contain internal identifiers and can’t be constructed by hand — made-up paths return 400 invalid poster path.

How the free tier works

Preview sizes are free and unlimited. The preview sizes t_ and s_ (up to 200 px — the size the share dialog gives you) are served without any quota, counter, or registration — hotlink as much as you like. It just works.

Larger sizes — l_ (300 px) and xl_ (up to 1200 px) — require a paid plan and are metered. We identify embedding sites by the Referer header your visitors’ browsers send; the first metered request from your domain auto-registers it — no account needed. Each registered domain gets a monthly bandwidth and request allowance for the paid sizes (see the table below).

When a domain exceeds its allowance — or embeds a size its plan doesn’t include — we never break your layout: instead of the poster you get a placeholder image with an upgrade note, until the period resets at the start of the next calendar month (or you upgrade).

See the difference

Drag across the poster to compare the free preview size with the paid sizes at the same display width — left of the line is s_ (200 px, what the share dialog gives you, upscaled exactly like an embedding page would), right is xl_. Small thumbnails and background tiles work fine on the free size; for grid cards you want l_, and for lightboxes, hero images, and high-density screens xl_ — both part of the paid plans.

s_ · 200 px · freel_/xl_ · paid tiers

Star Wars: Episode VII - The Force Awakens (2015)The Martian (2015)The Hateful Eight (2015)

Image sizes

Each poster exists in fixed derivative sizes, encoded as a filename prefix. Swap the prefix in a URL you copied to get another size of the same poster.

Original scans (o_) are never served through the embed CDN — they’re available to signed-in members as paid downloads.

Plans & quotas

Quotas count paid-size delivery (l_ and up) — the t_/s_ previews are always free and unmetered. They are per calendar month (UTC) and count per domain (or per API key). Every paid tier is also available with annual billing at 10 % off. Upgrades apply to your existing embeds — no URL changes needed. Manage plans in the embed console.

Claiming your domain

Auto-registered domains work without an account, but claiming your domain in the embed console gets you usage stats and lets you attach a paid tier. Verification takes a minute: add a DNS TXT record or a <meta> tag to your homepage — the console walks you through both.

API keys

If your embeds load without a browser Referer — server-side rendering into emails, native mobile apps, RSS readers — identify yourself with an API key instead: create a key and append ?k=mpdb_pk_… to the image URL. Keys take priority over the Referer when both are present. Revoke and re-issue from the console at any time.

Key hygiene: a key embedded in public page HTML is visible to anyone. Create an images-only key for that (no API scopes — it can serve posters but can’t call the Data API or MCP, so a copied key can’t hijack your API quota), and keep a separate private key with read/resolve scopes for server-side API and MCP use. The pin scope stays a per-key opt-in on top.

Data API

Beyond hotlinking a known image, the Data API lets you look films up programmatically — search by title, fetch a movie’s details, or list all of its poster variants — so your CMS can pull the right poster automatically. It uses the same API key as image embedding: every poster URL it returns already carries your ?k=, so the images that load stay attributed to you.

Authenticate with Authorization: Bearer mpdb_pk_… (or ?k=). Base URL /api/embed/v1:

Returned poster URLs honour your tier’s max size (Free → s_). Each plan includes a monthly call quota and a per-second rate limit (see your plan). Full machine-readable spec: openapi.json. Need a key? Create one.

Media servers — Plex, Jellyfin, Kodi

Running a home media server? The same API powers poster artwork for personal libraries: look titles up by IMDb or TMDB id (/movie?tmdb=…), by filename via /match, and fetch the country-aware primary poster first. Responses support ETag/If-None-Match — periodic library refreshes that hit a 304 don’t count against your quota. Add &source=jellyfin (or kodi, plex, …) so your usage page can break requests down per app.

The Personal plan (€15 / year, non-commercial) unlocks XL posters (~1200 px) for exactly this use case. Setup guides and plugin status per app: movieposterdb.com/integrations.

Batch resolve

POST /api/embed/v1/resolve takes a whole library in one call — release filenames, IMDb/TMDB ids or links, {title, year} pairs, mixed freely. Each item comes back with the detected method, a confidence score (≥ 90 is a safe auto-match), up to 5 candidates when ambiguous, and a signed poster URL honouring your defaults (country fallback chain, size, min width). The interactive version of the same engine is the Organizer.

curl -s -X POST 'https://movieposterdb.com/api/embed/v1/resolve' \
  -H 'Authorization: Bearer mpdb_pk_…' -H 'Content-Type: application/json' \
  -d '{"items":[{"q":"Inception.2010.1080p.BluRay.x264-GROUP.mkv"},
               {"imdb":"tt0133093"},{"title":"Heat","year":1995}],
       "defaults":{"country":"DE","size":"l","min_width":1000}}'

Billing is fair and simple: 1 item = 1 API request from your monthly quota — the saving versus single calls is the one HTTP roundtrip. Items per call are capped by plan: Free 5, Personal 50, Small 100, Medium/Large 200, XL/Enterprise 500. The endpoint never triggers crawls; unknown IMDb ids come back as unmatched with parsed.imdb set.

Stable movie URLs

Instead of hotlinking one specific poster file, you can embed one stable URL per movie:

https://posters.movieposterdb.com/m/tt1160419?k=mpdb_pk_…&s=l&cc=DE

The CDN answers with a short-lived redirect to the poster currently chosen for your key: the country-aware primary by default (auto), or whatever you pinned — in the Embedded movies editor, from the Organizer, or via an MCP agent. Change the pin and every page using the URL follows within ~10 minutes, no HTML edits. Works with any active embed key; s= is clamped to your plan’s max size, and the image behind the redirect counts against your quota exactly like a direct embed.

MCP server

The same interface speaks MCP (Model Context Protocol), so an assistant can work the archive directly — resolve messy title lists, browse editions, fetch signed image URLs and, if you allow it, pin the poster behind your stable URLs. Tools: resolve_titles, search_movies, get_movie, list_editions, pin_poster, random_movie, get_image_url.

{ "mcpServers": {
    "movieposterdb": {
      "url": "https://movieposterdb.com/api/mcp",
      "headers": { "Authorization": "Bearer mpdb_pk_…" }
    }
} }

MCP is never the laxer channel: it uses the same key, the same monthly quota (resolve_titles counts one request per line) and the same size clamp as the Data API. Key scopes control what an agent may do — read and resolve are on by default, pin is off until you enable it per key in API keys. Pins made by an agent appear in your Embedded movies list, badged as via agent.

Ground rules

• Use the URLs the site gives you — don’t guess or rewrite poster paths.
• Keep the link back to the poster page where practical; the archive grows through attribution.
• Don’t proxy or re-host the images to dodge quotas — spike-detection flags this and the domain gets suspended.
• Original scans stay off-limits for embedding, on every tier.