Images API

Retrieve, upload, and manage images for media items and users

The Images API provides comprehensive image management for Jellyfin, including retrieving images, uploading new images, deleting images, and accessing remote image providers.

Get Item Image

Retrieve an image for a specific item with optional transformations.

cURL

curl -X GET "https://your-server/Items/{itemId}/Images/Primary?maxWidth=500&quality=90" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -o "image.jpg"

Endpoint

method · string · required

GET

endpoint · string · required

/Items/{itemId}/Images/{imageType}

Path Parameters

itemId · string (GUID) · required

The item ID.

imageType · string · required

Type of image: Primary, Art, Backdrop, Banner, Logo, Thumb, Disc, Box, Screenshot, Menu, Chapter, BoxRear, Profile

imageIndex · integer

Image index for types that support multiple images (e.g., Backdrop).

Query Parameters

maxWidth · integer

Maximum image width to return.

maxHeight · integer

Maximum image height to return.

width · integer

Fixed image width to return.

height · integer

Fixed image height to return.

quality · integer · default: "90"

Image quality setting, from 0-100. Defaults to 90.

fillWidth · integer

Width of box to fill.

fillHeight · integer

Height of box to fill.

tag · string

Supply the cache tag from the item object to receive strong caching headers.

format · string

Image format: Original, Gif, Jpg, Png, Webp.

percentPlayed · number

Percent to render for the percent played overlay.

unplayedCount · integer

Unplayed count overlay to render.

blur · integer

Blur amount to apply to the image.

backgroundColor · string

Apply a background color for transparent images (hex color).

foregroundLayer · string

Apply a foreground layer on top of the image.

Response

Image file stream with appropriate content type.

Response Codes

• 200 - Success: Image stream returned
• 404 - Not Found: Item or image not found

---

Get Item Image Info

Retrieve information about all images for an item.

cURL

curl -X GET "https://your-server/Items/{itemId}/Images" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Endpoint

GET /Items/{itemId}/Images

Path Parameters

itemId · string (GUID) · required

The item ID.

Response

ImageInfos · array

Array of image information objects.

Show ImageInfo properties

ImageType · string

Type of image (Primary, Backdrop, etc).

ImageIndex · integer

Index for images that support multiples.

Path · string

File system path to the image.

Height · integer

Image height in pixels.

Width · integer

Image width in pixels.

Size · integer

File size in bytes.

BlurHash · string

BlurHash string for progressive image loading.

Response Codes

• 200 - Success: Image infos returned
• 404 - Not Found: Item not found

---

Upload Item Image

Upload or update an image for an item.

cURL

curl -X POST "https://your-server/Items/{itemId}/Images/Primary" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @image.jpg

Endpoint

method · string · required

POST

endpoint · string · required

/Items/{itemId}/Images/{imageType}

Path Parameters

itemId · string (GUID) · required

The item ID.

imageType · string · required

Type of image to upload.

imageIndex · integer

Image index for types that support multiple images.

Request Body

Binary image data. Supported formats: JPEG, PNG, GIF, WEBP.

Content-Type should be set appropriately (image/jpeg, image/png, etc).

Authorization

Requires elevation policy (administrator access).

Response Codes

• 204 - No Content: Image uploaded successfully
• 400 - Bad Request: Incorrect content type
• 404 - Not Found: Item not found

---

Delete Item Image

Delete an image from an item.

cURL

curl -X DELETE "https://your-server/Items/{itemId}/Images/Primary" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Endpoint

DELETE /Items/{itemId}/Images/{imageType}

Path Parameters

itemId · string (GUID) · required

The item ID.

imageType · string · required

Type of image to delete.

Query Parameters

imageIndex · integer

Image index for types that support multiple images.

Authorization

Requires elevation policy (administrator access).

Response Codes

• 204 - No Content: Image deleted successfully
• 404 - Not Found: Item not found

---

Update Image Index

Update the index order of an image.

cURL

curl -X POST "https://your-server/Items/{itemId}/Images/Backdrop/0/Index?newIndex=2" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Endpoint

POST /Items/{itemId}/Images/{imageType}/{imageIndex}/Index

Path Parameters

itemId · string (GUID) · required

The item ID.

imageType · string · required

Type of image.

imageIndex · integer · required

Current image index.

Query Parameters

newIndex · integer · required

New image index.

Authorization

Requires elevation policy (administrator access).

Response Codes

• 204 - No Content: Image index updated
• 404 - Not Found: Item not found

---

User Images

Manage user profile images.

Get User Image

Get

curl -X GET "https://your-server/Users/{userId}/Images/Primary" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -o "profile.jpg"

GET /Users/{userId}/Images/Primary

Upload User Image

Upload

curl -X POST "https://your-server/UserImage?userId={userId}" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @profile.jpg

POST /UserImage

Delete User Image

Delete

curl -X DELETE "https://your-server/UserImage?userId={userId}" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

DELETE /UserImage

Query Parameters

userId · string (GUID)

User ID. If not provided, uses the authenticated user.

Response Codes

• 200 - Success: Image returned (GET)
• 204 - No Content: Operation completed (POST/DELETE)
• 403 - Forbidden: User does not have permission
• 404 - Not Found: User not found

---

Remote Images

Access remote image providers for metadata.

Get Available Remote Images

cURL

curl -X GET "https://your-server/Items/{itemId}/RemoteImages?type=Primary&limit=20" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Endpoint

GET /Items/{itemId}/RemoteImages

Path Parameters

itemId · string (GUID) · required

The item ID.

Query Parameters

type · string

Filter by image type (Primary, Backdrop, etc).

startIndex · integer

Record index to start at.

limit · integer

Maximum number of images to return.

providerName · string

Filter by specific image provider.

includeAllLanguages · boolean · default: "false"

Include images in all languages.

Response

Images · array

Array of remote image objects.

Show RemoteImageInfo properties

Url · string

URL to the remote image.

ThumbnailUrl · string

URL to a thumbnail version.

ProviderName · string

Name of the image provider.

Type · string

Image type.

Width · integer

Image width.

Height · integer

Image height.

Language · string

Image language.

TotalRecordCount · integer

Total number of available images.

Providers · string[]

List of available provider names.

Response Codes

• 200 - Success: Remote images returned
• 404 - Not Found: Item not found

---

Get Remote Image Providers

Get a list of available remote image providers for an item.

cURL

curl -X GET "https://your-server/Items/{itemId}/RemoteImages/Providers" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Endpoint

GET /Items/{itemId}/RemoteImages/Providers

Response

Providers · array

Array of image provider information.

Show ImageProviderInfo properties

Name · string

Provider name.

SupportedImages · string[]

Array of supported image types.

Response Codes

• 200 - Success: Providers returned
• 404 - Not Found: Item not found

---

Download Remote Image

Download a remote image and apply it to an item.

cURL

curl -X POST "https://your-server/Items/{itemId}/RemoteImages/Download?type=Primary&imageUrl=https://..." \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Endpoint

POST /Items/{itemId}/RemoteImages/Download

Path Parameters

itemId · string (GUID) · required

The item ID.

Query Parameters

type · string · required

Image type to download.

imageUrl · string

URL of the remote image to download.

Authorization

Requires elevation policy (administrator access).

Response Codes

• 204 - No Content: Remote image downloaded successfully
• 404 - Not Found: Item or remote image not found

---

Named Item Images

Retrieve images for named items (artists, genres, persons, etc).

Get Artist Image

Artist

curl -X GET "https://your-server/Artists/{name}/Images/Primary/0" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

GET /Artists/{name}/Images/{imageType}/{imageIndex}

Get Genre Image

Genre

curl -X GET "https://your-server/Genres/{name}/Images/Primary" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

GET /Genres/{name}/Images/{imageType}

Get Person Image

Person

curl -X GET "https://your-server/Persons/{name}/Images/Primary" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

GET /Persons/{name}/Images/{imageType}

Path Parameters

name · string · required

Name of the artist, genre, or person.

imageType · string · required

Type of image.

imageIndex · integer

Image index (for artists).

Supports the same query parameters as item images (maxWidth, quality, format, etc).

Response Codes

• 200 - Success: Image stream returned
• 404 - Not Found: Named item not found