export_pdf
Build a PDF from an Immich album or selected photos/videos, embedding dates, places, camera details, people, and tags. Add captions with your analysis; video frames are included directly in the PDF.
Instructions
Build a PDF (cover, index, places, one section per asset) from an album or a
list of assets, on the machine running this server. Immich metadata (date, place,
camera, people, tags) is always included; pass captions {asset_id: text} with
what you saw to add your analysis. Video frames go straight into the PDF and cost
no tokens (up to 120 per video). The PDF never enters the conversation unless
return_base64=True. If the user asked for a PDF without saying how they want
it, call get_export_preview first and ask them about the choices it lists.
Keep the selection coherent: one story per PDF. Never mix unrelated assets
(two videos about different things, photos from different events) just to
show more; if the user's material spans several stories, offer one PDF per
story instead.
Args:
album_id: Album UUID, or asset_ids: explicit asset UUIDs (exactly one of the two).
output_path: Where to write (default ~/Desktop/<title>.pdf). Existing files are never overwritten.
title: Cover title (default: album name or "Immich export <date>").
captions: {asset_id: text} written after looking at the images.
layout: 'detail' (one asset per page with its data, default), 'grid' (six per page)
or 'photobook' (one asset per page, image as large as it fits, caption under
it; a video with several chosen frames unfolds into one full page per frame).
frames_per_video: Frames per video, evenly spaced (0-120, default 4; 0 = poster only).
frame_interval: One frame every N seconds instead of frames_per_video (same 120 cap).
frame_times: {asset_id: [seconds, ...]} exact moments for specific videos, chosen
after looking at their frames ("the representative frame"). Wins over
frames_per_video/frame_interval for the listed videos; others keep the spread.
frame_captions: {asset_id: [text, ...]} one caption per extracted frame, in frame
order (photobook prints each on its frame's page; other layouts ignore them).
image_size: 'original' (default): photos go in at the stored file's quality,
re-encoded to at most 3000px (a format the server cannot decode, like
some HEIC, falls back to preview with a note); 'preview' (1440px) or
'thumbnail' for smaller files.
frame_size: video frame size in the PDF: 'auto' (default, same as 'preview':
quality is free inside the PDF) or 'thumbnail' for a smaller file.
language: 'en' (default) or 'es' for the fixed labels on the pages (Index,
Places, Camera, page numbers); captions stay in whatever language you wrote.
map: Draw an OpenStreetMap map on the Places page when assets carry GPS
(default True; tiles come from tile.openstreetmap.org, the only
third-party call this server makes — pass map=False to skip it).
cover, index, places: Include each front-matter page (all default True;
turn them off for a print-ready photobook of bare pages).
footer: 'full' (plugin name, server and page number, default), 'pages'
(just the page number) or 'none'.
header: Repeat the title at the top of every page except the cover
(default False).
videos_position: Where the video pages (frame strips or frame pages) go:
'mixed' with the photos in the general order (default), 'first' or 'last'.
order: 'auto' (albums read oldest to newest, like the frames inside a video;
asset_ids keep the order you passed), 'oldest', 'newest' or 'given'.
confirm: Only asked for when explicit asset_ids mix videos more than 90 days
apart (different stories). Pass True only when the user themselves asked
to mix them; exporting a whole album never needs it.
limit: Max assets (1-500, default 100).
return_base64: Also return the PDF bytes (skipped above 2 MB; every MB is
roughly 350k tokens in the conversation).
Returns: JSON {path, pages, bytes, assets_included, assets_skipped:[{id, reason}], warnings:[...]}.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| map | No | ||
| cover | No | ||
| index | No | ||
| limit | No | ||
| order | No | auto | |
| title | No | ||
| footer | No | full | |
| header | No | ||
| layout | No | detail | |
| places | No | ||
| confirm | No | ||
| album_id | No | ||
| captions | No | ||
| language | No | en | |
| asset_ids | No | ||
| frame_size | No | auto | |
| image_size | No | original | |
| frame_times | No | ||
| output_path | No | ||
| return_base64 | No | ||
| frame_captions | No | ||
| frame_interval | No | ||
| videos_position | No | mixed | |
| frames_per_video | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |