Images Configuration

The images option controls how the client builds image URLs. You can toggle HTTPS and set default sizes for each image category so they are applied automatically across all responses without needing to specify a size on every call.

const tmdb = new TMDB(apiKey, {
	images: {
		secure_images_url: true,
		default_image_sizes: {
			posters: "w500",
			backdrops: "w1280",
			logos: "w185",
			profiles: "w185",
			still: "w300",
		},
	},
});

ImagesConfig

secure_images_url

Type: boolean · Default: true

When true, image URLs use the HTTPS base URL (https://image.tmdb.org/t/p/). When false, the HTTP base URL is used (http://image.tmdb.org/t/p/).

Set this to false only in environments where HTTPS is not available. For all standard use cases, leave it as true.

default_image_sizes

Type: Partial<DefaultImageSizesConfig> · Optional

Defines fallback sizes for each image type. These are applied whenever a size is not explicitly specified at call time. All keys are optional.

Image URL Structure

A final image URL is assembled as:

{base_url}{size}{file_path}

For example, using w500 for a poster:

https://image.tmdb.org/t/p/w500/abc123.jpg

Prefer original only when you need the full-resolution asset and are willing to accept larger file sizes. For UI thumbnails, sized variants like w500 or w780 are recommended.

Useful Links