Files
immich-magic-proxy/docs/config/ipp-options.md
T
Alan Grainger 7a9ff2e6ee Update docs
2026-10-07 16:51:46 +13:00

6.4 KiB

General options

Top-level options under ipp.* that don't belong to the Gallery, Lightbox or Metadata groups.

Example

Serve full-resolution images both when zooming in the lightbox and when downloading:

{
  "ipp": {
    "maxDownloadQuality": "fullsize",
    "maxZoomQuality": "fullsize"
  }
}

responseHeaders

Type: object

Change the headers sent with photos, videos and static files. The default is a 30-day Cache-Control and a permissive CORS header. The "download all" zip is always sent with Cache-Control: no-store, and the gallery page uses its own gallery.cacheTime.

{
  "ipp": {
    "responseHeaders": {
      "Cache-Control": "public, max-age=2592000",
      "Access-Control-Allow-Origin": "*"
    }
  }
}

maxDownloadQuality

Type: string · Default: "original"

Highest quality served for a download (the download button and "download all" zip).

  • "original" - the full-resolution original file (default).
  • "fullsize" - full resolution but always browser-displayable: the original for JPEG/PNG/WebP, Immich's converted full-size image for RAW/HEIF, in JPEG or WebP per the server's image settings.
  • "preview" - only the ~1440px preview, in JPEG or WebP per the server's image settings.

maxZoomQuality

Type: string · Default: "preview"

Highest quality the lightbox loads when you zoom in past fit-to-screen.

  • "preview" - keep the preview (default; zoom is capped to the preview's real pixels).
  • "fullsize" - load the full-resolution browser-displayable image on zoom, like the Immich web viewer.

"original" is not an option here, because an original can be a RAW or DNG file the browser cannot display.

This setting is independent of allowDownload: the download buttons can be off while zoom is on. The full-resolution image is only available when the share's own "Allow downloads" toggle in Immich is on, and the photo is a JPEG, PNG or WebP. For other formats, or shares with downloads off in Immich, the lightbox stays on the preview. To get full-resolution zoom without showing download buttons, leave downloads on in Immich and set allowDownload to 0.

motionPhotos

Type: bool · Default: true

Show motion photos (Live Photos) - an indicator on the gallery thumbnail, and a toggle in the lightbox that plays the photo's short clip and returns to the still when it ends. The toggle stays on: each motion photo the visitor moves to plays its clip automatically until they switch it off.

Clips are only fetched while the toggle is on, so leaving this on costs no extra bandwidth for visitors who never use it. Set to false to serve motion photos as plain stills:

{
  "ipp": {
    "motionPhotos": false
  }
}

downloadedFilename

Type: int · Default: 0

The filename of the downloaded image.

  • 0 - the original filename if available, falling back to the Immich asset ID.
  • 1 - the Immich asset ID number.
  • 2 - a shortened version of the asset ID: img_ plus the first 8 characters of the asset ID.

allowDownload

Type: int · Default: 0

Show the download buttons: the "download all" zip, the multi-select download, and the download button in the lightbox. This only shows or hides the buttons; image quality is set by maxDownloadQuality and maxZoomQuality.

  • 0 - downloads off.
  • 1 - follow the Immich share's own download setting (example).
  • 2 - always on.

The bulk-zip and per-asset buttons can be toggled independently once downloads are allowed - see gallery.showDownloadZip and lightbox.showDownload.

Note

With 2, IPP shows the download buttons even on shares whose own download toggle in Immich is off. Immich still refuses to serve those shares' original files, so on such a share:

  • Videos download as the playback version, usually an .mp4, instead of the original.
  • Photos download at maxDownloadQuality if it is below original. With original they fail.
  • Gifs always download as the original file, so they fail.

To be sure every download works at full quality, leave the share's download permission on in Immich.

uploadUrl

Type: string · Default: "/upload"

Where the optional upload service (the immich-public-proxy-upload container) is served. A share whose "Allow public user to upload" option is on in Immich then shows an "Add photos" button in the gallery header, which opens that share's page on the upload service. To set up the service, see Let visitors send photos back.

  • A path, such as the default /upload, means the service is on IPP's own hostname under that path. Before showing the button, the gallery page checks that the upload service answers ok at <path>/healthcheck, so an install without the upload container never shows a dead button. When nothing is routed there, IPP answers that path itself with an empty 204.
  • An absolute URL, such as https://upload.example.com, means the service has a hostname of its own. It is trusted without a check. The URL may include a path, such as https://photos.example.com/upload, which points at the same place as the default but without the check.
  • An empty string never shows the button.

Type: bool · Default: true

Serve shared links that have a custom URL in Immich at /s/<slug> as well as /share/<key>. Set to false to return a 404 for slug links, so that only the key form works.

showHomePage

Type: bool · Default: true

Set to false to remove the IPP shield page at / and at /share.

{
  "ipp": {
    "showHomePage": false
  }
}

Type: object

Gallery-page options. See Gallery.

lightbox

Type: object

Lightbox options. See Lightbox.

showMetadata

Type: object

Description / EXIF / location reveal controls. See Metadata.

customInvalidResponse

Type: various

Send a custom response instead of the default 404. See Error responses.