Image Types

  • poster_path: The poster_path is first searched in the language you specify in your query. If matching image is presented, it defaults to the highest-rated image in the media’s original language. If that image is also unavailable, it falls back to the highest-rated image overall.

while the language query parameter supports regional lookups, regional variants for images are not yet supported—this feature will be added in the future.

  • backdrop_path: Since 99% of backdrops don’t contain a language, the default lookup for a backdrop is to simply query for the highest rated backdrop with no language. If it doesn’t exist, then we return the overall highest rated.

  • still_path: Like backdrops, TV episode images don’t inherently have languages. We query for the highest rated.

Default Language

When querying one of the /images methods, the language parameter filters the results based on the specified language. However, since you may want to retrieve images in multiple languages, it’s recommended to use the include_image_language query parameter. This acts as a fallback, allowing you to include images tagged with additional languages or those without any language tag.

Below is an example of how to request images tagged with English (en) while also including images that have no language tag.

Example getting English and no language images
curl --request GET \
     --url 'https://api.themoviedb.org/3/movie/550/images?language=en-US&include_image_language=en,null' \
     --header 'Authorization: Bearer {ACCESS_TOKEN}'
     --header 'accept: application/json'

Notice the include_image_language parameter. The query (en,null) retrieves all images tagged with English (en) as well as those without a language tag (null).

Even better, you can use this query parameter append_to_response to fetch an image in a single request, e.g:

Example with append to response
curl --request GET \
     --url 'https://api.themoviedb.org/3/movie/550?append_to_response=images&language=en-US&include_image_language=en,null' \
     --header 'Authorization: Bearer {ACCESS_TOKEN}' \
     --header 'accept: application/json'