amodb documentation
Start with the quickstart to make your first call in two minutes. Then read how keys, rate limits, errors, languages and images work. amodb keeps TMDB v3 and OMDb paths and JSON, so most pages here explain what is the same, what amodb adds and the few places where it differs.
Base URLs
| Use | Base URL | Key parameter |
|---|---|---|
| TMDB v3 style | https://api.amodb.dev/3 | api_key or Authorization: Bearer |
| OMDb style | https://api.amodb.dev/omdb/ | apikey |
| Images | https://img.amodb.dev/t/p/{size}/{file} | none |
| Plan catalog | https://api.amodb.dev/plans | none |
Get started
-
Make your first amodb call: get a key, request movie details in curl, JavaScript, Python, PHP or Go, then load the poster from img.amodb.dev. Under 2 minutes.
-
How to send your amodb key: api_key in the query, an Authorization Bearer header, or apikey for OMDb calls. Key format, storage, rotation and the 401 errors.
Concepts
-
amodb limits each key by requests per minute in a sliding 60 second window: 20, 40 or 120 by plan. Read the rate limit headers and handle 429 with Retry-After.
-
Every amodb error with its HTTP status, TMDB status_code and message, plus the OMDb error shape. What each one means and what your client should do next.
-
amodb serves titles, overviews and names in 14 languages. Pass a TMDB style tag such as ru-RU or pt-BR in language; any other tag falls back to English.
-
Load posters, backdrops and profile photos from img.amodb.dev with TMDB paths and sizes from w92 to original. No key, 30 day cache, one URL pattern for all.
API reference
-
Movie details API with the same paths and JSON as TMDB v3. Get one movie by id, add credits, ratings and moods with append_to_response, in 14 languages.
-
GET TV series API
TV series API with the same paths and JSON as TMDB v3. Get a show by id with seasons, networks and the next episode, plus content ratings and watch providers.
-
GET TV seasons and episodes API
TV seasons and episodes API with the same paths and JSON as TMDB v3. Read a season with all its episodes, or one episode with air date, runtime and still.
-
Person details API with the same paths and JSON as TMDB v3. Get an actor or crew member by id, with biography, filmography, external ids and the popular list.
-
GET Credits API
Credits API with the same paths and JSON as TMDB v3. Get cast and crew for movies, series, seasons and episodes, with order, department and job fields.
-
GET Search API
Search API with the same paths and JSON as TMDB v3. Find movies, TV shows, people, collections, companies and keywords by text, with year filters and paging.
-
GET Discover API
Discover API with the same filters as TMDB v3. List movies and TV shows by genre, cast, company, keyword, year, rating, runtime and provider, with sorting.
-
GET Trending and list endpoints
Trending movies API with TMDB v3 paths: day and week charts, plus now playing, popular, top rated and upcoming lists for movies and TV, cached for 30 minutes.
-
Genre list API with TMDB v3 paths: movie and TV genre ids with translated names, plus countries, languages, jobs, certifications and watch provider lists.
-
Movie images API with TMDB v3 paths: list posters, backdrops, logos and stills per title, then load them from img.amodb.dev in 10 sizes with no key.
-
Movie videos API with TMDB v3 paths: list trailers, teasers, clips and featurettes for a movie or series, then filter by type and language in your code.
-
GET Translations API
Movie translations API with TMDB v3 paths: read every stored title, overview and tagline of a movie, series or episode in all its languages at once.
-
GET Keywords API
Movie keywords API with TMDB v3 paths: list plot tags for a movie or series, look up a keyword, list its movies and combine ids with discover with_keywords.
-
GET Collections API
Movie collections API with TMDB v3 paths: fetch a franchise by id with all its parts, read belongs_to_collection on a movie, and search collections by name.
-
Look up production companies and TV networks with TMDB v3 paths. Read name, country and logo by id, then filter discover by company or network id.
-
Movie ratings API that returns IMDb, Kinopoisk, Metacritic, Rotten Tomatoes and TMDB scores for a title in one call, with null for any source not known.
-
Look up a movie, series or person by IMDb, TVDB, Wikidata or Kinopoisk id with the TMDB find endpoint, and read external ids and Wikidata facts for a title.
-
OMDb API compatible endpoint at api.amodb.dev/omdb/. Look up by i or t, search with s, read the Ratings array and keep your client by changing the base URL.
-
GET Mood meters
Movie mood API with 0 to 10 mood meters per title. Read moods for a movie or series, merge them with append_to_response=moods and build badges or filters.
-
GET Soundtracks
Movie soundtrack API that returns the soundtrack album of a movie or TV series with its track list. Call the endpoint or add append_to_response=soundtracks.
-
GET Cinema showtimes
Movie showtimes API that returns venues and screening times for a movie in one country, or a country summary. Merge it into details or pair it with now_playing.
Resources
-
Dated list of changes to the amodb API, the img.amodb.dev image host, plans and the website. New entries go on top, with what changed and what you need to do.
-
How to check whether amodb is up: the public health endpoint, the error codes that point to an incident, and how to report a problem with the details we need.
More guides and indexes
-
Every amodb endpoint with its path, parameters, request samples in five languages and a real JSON response. TMDB v3 and OMDb compatible.
-
Step by step tutorials for the amodb API: search, details, images, languages and OMDb calls in common stacks, each with code you can copy and run.
-
Side by side comparisons of amodb with other movie and TV metadata APIs: compatibility, languages, limits, images and prices, with numbers you can check.
-
How teams use amodb for movie and TV data: catalogs, media servers, recommendation tools, bots and research, with the endpoints and limits each case needs.