​
Image Types

When querying for images in our API, the behavior of image path fields poster_path, backdrop_path, and still_path varies based on language preferences, availability, and fallback logic. Below is a detailed explanation of how each field operates:

Poster_path

  • Language Priority: The system first attempts to retrieve the poster in the language specified in your query (e.g., en or fr).

  • Fallback Mechanism:

    • If no poster exists in the requested language, it defaults to the highest-rated poster in the media’s original language, if available.

    • If neither is found, it falls back to the overall highest-rated poster, regardless of language.

  • Regional Variants: Although the language query parameter supports regional lookups (e.g., en-US or fr-CA), regional variants for images are not currently supported. This functionality is planned for a future update.

Backdrop_path

  • Language Consideration: Most backdrops lack a specific language designation. As a result, the default behavior is to return the highest-rated backdrop with no language specified.

  • Fallback: If no language-agnostic backdrop is available, the system returns the overall highest-rated backdrop, regardless of language.

Still_path

  • TV Episode Images: Similar to backdrops, still images for TV episodes do not inherently have associated languages.

  • Query Behavior: The system retrieves the highest-rated still image available, with no language-based filtering applied.

When querying /images, the language parameter filters by language tags. Use include_image_language to add images from other languages or untagged ones. Take a look below where we give an example of requesting the images tagged with English and also those not tagged with any language.

  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. This query (en,null) is looking for all images that match English and those that haven’t been set yet (null).

Better yet, you can do query this image method in a single request by using 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'