Files
immich-magic-proxy/docs/config/ipp-options.md
T
2026-09-04 23:27:28 +12:00

5.1 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 your web responses. The default is a 30-day Cache-Control and a permissive CORS header. These apply to photos, videos and static files. The "download all" zip is always sent with Cache-Control: no-store to prevent CDN issues, 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 JPEG for RAW/HEIF.
  • "preview" - only the ~1440px preview JPEG.

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" - upgrade to the full-resolution browser-displayable image on zoom, à la the Immich web viewer.

"original" is intentionally not an option (it could be an unviewable RAW/DNG or a huge file).

Independent of allowDownload - your download UI can be off while zoom is on. It only does anything where Immich can serve full resolution: the share's own "allow downloads" toggle in Immich must be on (the full-res image comes from the original file, which Immich gates on that toggle), and the format must be web-displayable (JPEG/PNG/WebP). Otherwise (RAW/HEIF, or a share with Immich downloads off) the lightbox stays on the preview. To enable zoom-up, leave the Immich share's download permission on and use allowDownload to control whether the download buttons appear.

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 UI - the "download all" zip, the multi-select download, and the per-asset download button in the lightbox. Purely a UI switch; it has no effect on image quality (see maxZoomQuality / maxDownloadQuality).

  • 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 UI even on shares whose own download toggle in Immich is off - but Immich still refuses to serve those shares' original files, so IPP works around it where it can:

  • Videos are downloaded as the transcoded playback file instead of the original (the same stream the visitor can already watch). The filename extension follows the transcoded format, typically .mp4.
  • Photos download normally as long as maxDownloadQuality is below original; with maxDownloadQuality: original they fail, because the original file is exactly what Immich is refusing to serve.
  • Gifs always download as the original file (their preview is a static frame), so they fail on these shares.

To guarantee full-quality downloads of everything, leave the share's download permission on in Immich.

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.