Images API - Jellyfin Server

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

const response = await fetch(
  'https://your-server/Items/{itemId}/Images/Primary?maxWidth=500&quality=90',
  {
    headers: {
      'Authorization': 'MediaBrowser Token=YOUR_API_KEY'
    }
  }
);
const blob = await response.blob();

import requests

response = requests.get(
    f'https://your-server/Items/{item_id}/Images/Primary',
    params={'maxWidth': 500, 'quality': 90},
    headers={'Authorization': 'MediaBrowser Token=YOUR_API_KEY'}
)
with open('image.jpg', 'wb') as f:
    f.write(response.content)

Endpoint

string

required

GET

string

required

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

Path Parameters

string (GUID)

required

The item ID.

string

required

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

integer

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

Query Parameters

integer

Maximum image width to return.

integer

Maximum image height to return.

integer

Fixed image width to return.

integer

Fixed image height to return.

integer

default:"90"

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

integer

Width of box to fill.

integer

Height of box to fill.

string

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

string

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

number

Percent to render for the percent played overlay.

integer

Unplayed count overlay to render.

integer

Blur amount to apply to the image.

string

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

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

string (GUID)

required

The item ID.

Response

array

Array of image information objects.

Show ImageInfo properties

string

Type of image (Primary, Backdrop, etc).

integer

Index for images that support multiples.

string

File system path to the image.

integer

Image height in pixels.

integer

Image width in pixels.

integer

File size in bytes.

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

string

required

POST

string

required

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

Path Parameters

string (GUID)

required

The item ID.

string

required

Type of image to upload.

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

string (GUID)

required

The item ID.

string

required

Type of image to delete.

Query Parameters

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

string (GUID)

required

The item ID.

string

required

Type of image.

integer

required

Current image index.

Query Parameters

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

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

string (GUID)

required

The item ID.

Query Parameters

string

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

integer

Record index to start at.

integer

Maximum number of images to return.

string

Filter by specific image provider.

boolean

default:"false"

Include images in all languages.

Response

array

Array of remote image objects.

Show RemoteImageInfo properties

string

URL to the remote image.

string

URL to a thumbnail version.

string

Name of the image provider.

string

Image type.

integer

Image width.

integer

Image height.

string

Image language.

integer

Total number of available images.

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

array

Array of image provider information.

Show ImageProviderInfo properties

string

Provider name.

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

string (GUID)

required

The item ID.

Query Parameters

string

required

Image type to download.

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

string

required

Name of the artist, genre, or person.

string

required

Type of image.

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

​Get Item Image

​Endpoint

​Path Parameters

​Query Parameters

​Response

​Response Codes

​Get Item Image Info

​Endpoint

​Path Parameters

​Response

​Response Codes

​Upload Item Image

​Endpoint

​Path Parameters

​Request Body

​Authorization

​Response Codes

​Delete Item Image

​Endpoint

​Path Parameters

​Query Parameters

​Authorization

​Response Codes

​Update Image Index

​Endpoint

​Path Parameters

​Query Parameters

​Authorization

​Response Codes

​User Images

​Get User Image

​Upload User Image

​Delete User Image

​Query Parameters

​Response Codes

​Remote Images

​Get Available Remote Images

​Endpoint

​Path Parameters

​Query Parameters

​Response

​Response Codes

​Get Remote Image Providers

​Endpoint

​Response

​Response Codes

​Download Remote Image

​Endpoint

​Path Parameters

​Query Parameters

​Authorization

​Response Codes

​Named Item Images

​Get Artist Image

​Get Genre Image

​Get Person Image

​Path Parameters

​Response Codes

Get Item Image

Endpoint

Path Parameters

Query Parameters

Response

Response Codes

Get Item Image Info

Endpoint

Path Parameters

Response

Response Codes

Upload Item Image

Endpoint

Path Parameters

Request Body

Authorization

Response Codes

Delete Item Image

Endpoint

Path Parameters

Query Parameters

Authorization

Response Codes

Update Image Index

Endpoint

Path Parameters

Query Parameters

Authorization

Response Codes

User Images

Get User Image

Upload User Image

Delete User Image

Query Parameters

Response Codes

Remote Images

Get Available Remote Images

Endpoint

Path Parameters

Query Parameters

Response

Response Codes

Get Remote Image Providers

Endpoint

Response

Response Codes

Download Remote Image

Endpoint

Path Parameters

Query Parameters

Authorization

Response Codes

Named Item Images

Get Artist Image

Get Genre Image

Get Person Image

Path Parameters

Response Codes