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. It can also opt in to expanding relative TMDB image paths returned by the API into full URLs.

Using tmdb.images

tmdb.images is a synchronous URL builder — no HTTP request, no async. It exposes one method per TMDB image category. Each method accepts a file path (returned by any API response) and an optional size. When the size is omitted the configured default for that category is used.

poster(path, size?)

Builds a URL for a poster image (poster_path field on movies, TV series, collections, and seasons).

poster_path is optional on most response types — guard before calling.

const movie = await tmdb.movies.details({ movie_id: 550 });

if (movie.poster_path) {
	const posterUrl = tmdb.images.poster(movie.poster_path, "w500");
	// → "https://image.tmdb.org/t/p/w500/pB8BM7pdSp6B6Ih7QZ4DrQ3PmJK.jpg"

	// Omit size to use the configured default (w500)
	const posterUrlDefault = tmdb.images.poster(movie.poster_path);
}

Size options (PosterSize): w92 · w154 · w185 · w342 · w500 · w780 · original

backdrop(path, size?)

Builds a URL for a backdrop image (backdrop_path field on movies and TV series).

backdrop_path is optional — guard before calling.

const tv = await tmdb.tv_series.details({ series_id: 1396 });

if (tv.backdrop_path) {
	const backdropUrl = tmdb.images.backdrop(tv.backdrop_path, "w1280");
	// → "https://image.tmdb.org/t/p/w1280/tsRy63Mu5cu8etL1X7ZLyf7UP1M.jpg"
}

Size options (BackdropSize): w300 · w780 · w1280 · original

logo(path, size?)

Builds a URL for a logo image (logo_path field on companies and networks).

const network = await tmdb.networks.details({ network_id: 213 });

const logoUrl = tmdb.images.logo(network.logo_path, "w185");
// → "https://image.tmdb.org/t/p/w185/alqLicR1ZMHMaZGP3xRQxn9sq7p.png"

Size options (LogoSize): w45 · w92 · w154 · w185 · w300 · w500 · original

profile(path, size?)

Builds a URL for a profile image (profile_path field on people).

profile_path is optional — guard before calling.

const person = await tmdb.people.details({ person_id: 31 });

if (person.profile_path) {
	const profileUrl = tmdb.images.profile(person.profile_path, "w185");
	// → "https://image.tmdb.org/t/p/w185/r7WLn4Kbnqb6oJ8TmSI0e3GKEAO.jpg"
}

Size options (ProfileSize): w45 · w185 · h632 · original

still(path, size?)

Builds a URL for a TV episode still image (still_path field on TV episodes).

still_path is optional — guard before calling.

const episode = await tmdb.tv_episodes.details({
	series_id: 1396,
	season_number: 1,
	episode_number: 1,
});

if (episode.still_path) {
	const stillUrl = tmdb.images.still(episode.still_path, "w300");
	// → "https://image.tmdb.org/t/p/w300/ydlY3iPfeOAvu8gVqrxPoMvzNCn.jpg"
}

Size options (StillSize): w92 · w185 · w300 · original

Configuring Default Sizes

Pass the images option to the TMDB constructor to configure HTTPS mode and set per-category default sizes. These defaults apply whenever a size is not passed explicitly at call time.

const tmdb = new TMDB(apiKey, {
	images: {
		secure_images_url: true,
		autocomplete_paths: 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.

autocomplete_paths

Type: boolean · Default: false

When enabled, the client automatically rewrites supported image path fields in API responses into full image URLs using the current image configuration.

This affects relative TMDB paths such as poster_path, backdrop_path, profile_path, logo_path, still_path, and file_path values inside image collections like posters or backdrops.

const tmdb = new TMDB(apiKey, {
	images: {
		autocomplete_paths: true,
		default_image_sizes: {
			posters: "original",
		},
	},
});

const movie = await tmdb.movies.details({ movie_id: 550 });

console.log(movie.poster_path);
// "https://image.tmdb.org/t/p/original/e1mjopzAS2KNsvpbpahQ1a6SkSn.jpg"

If default_image_sizes is not configured, the built-in per-type defaults are used instead:

This option is disabled by default to preserve the original TMDB response semantics, where image fields contain relative paths that can be passed to tmdb.images.* manually.

image_language_priority

Type: ImageLanguagePriorityConfig · Optional

Controls the order of image items inside collection arrays (e.g. posters, backdrops) when autocomplete_paths is enabled. Accepts a partial map of collection key → priority list.

Each priority entry is applied in order:

No items are ever dropped — only their order changes. Items not matched by any entry are appended at the end.

const tmdb = new TMDB(apiKey, {
	images: {
		autocomplete_paths: true,
		image_language_priority: {
			// 1. textless posters first  2. English  3. any remaining
			posters: ["null", "en", "*"],
		},
	},
});

// When autocomplete_paths resolves the posters array, items are reordered
// so the first poster is the best match according to the priority list.
const images = await tmdb.movies.images({ movie_id: 550 });
console.log(images.posters[0]); // → best match poster URL

Supported collection keys: backdrops, logos, posters, profiles, stills.

auto_include_image_language

Type: boolean · Default: false

When true, the client automatically derives include_image_language from the language codes declared in image_language_priority and injects it into every .images() request. This ensures TMDB actually returns the language variants the priority config expects to sort.

The injected value is the union of all language codes across all configured collections, with "*" excluded (it has no meaning as an HTTP query parameter). An explicit include_image_language at the call site always takes precedence.

Requires image_language_priority to be configured; has no effect without it.

const tmdb = new TMDB(apiKey, {
	images: {
		autocomplete_paths: true,
		image_language_priority: { posters: ["null", "en", "*"] },
		// Automatically sends include_image_language: ["null", "en"] on every .images() call
		auto_include_image_language: true,
	},
});

// No need to pass include_image_language manually — it's injected automatically
const images = await tmdb.movies.images({ movie_id: 550 });

// Explicit call-site value always takes precedence over the injected default
const customImages = await tmdb.movies.images({
	movie_id: 550,
	include_image_language: ["fr", "null"],
});

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.

When autocomplete_paths is enabled, these defaults are also used to expand image fields returned by API responses.

Useful Links