drolosoft/immich-photo-manager

Добавляет существующие активы в альбом. Используйте это для подбора альбомов из результатов поиска или других списков активов. Активы могут одновременно принадлежать нескольким альбомам. Побочный эффект: изменяет членство в альбоме. Аргументы: album_id: UUID целевого альбома. asset_ids: Список UUID активов для добавления в альбом. Возвращает: JSON с album_id, количеством добавленных элементов и деталями успеха/ошибки для каждого актива.

Forget the plugin's notes on assets (reviews and actions). Only the plugin's own key is removed; metadata other apps stored stays. Side effect: deletes the notes on the server. Args: asset_ids: The assets to clear. Returns: JSON with success, how many assets were cleared, and a failed array of {asset_id, error}. Success is true only when nothing failed.

Публикует комментарий (или лайк) в общем альбоме или на одном элементе в нём. Побочный эффект: активность видна всем, с кем альбомом поделились. Args: album_id: Альбом, в котором нужно оставить комментарий. comment: Текст комментария. Оставьте пустым, если отправляете лайк. asset_id: Прикрепите комментарий/лайк к этому элементу вместо альбома. like: True, чтобы отправить лайк вместо комментария. Возвращает: JSON с id и типом созданной активности.

Создает новый альбом, опционально предварительно заполненный фотографиями. Используйте это, чтобы организовать фото в коллекции. Побочный эффект: создает новый альбом в Immich. Аргументы: name: Отображаемое имя альбома (например, 'Roma, Italia', 'Birthday 2024'). description: Необязательный текст описания альбома. asset_ids: Необязательный список UUID ресурсов, добавляемых сразу при создании. Возвращает: JSON с id, name и количеством ресурсов нового альбома.

Create an "on this day" memory from chosen assets. Use this after curating a set of photos from the same past date (e.g. via search_metadata with a date range) to make them show up in Immich's memories feed. Side effect: creates a memory on the server. Args: memory_at: ISO date the memory is shown on (usually today's month and day). year: The past year the memory looks back to (required by Immich). asset_ids: Assets to include. May be empty, but an empty memory shows nothing. Returns: JSON with the created memory's id, type, memory_at, the year it remembers, is_saved, asset_count and a trimmed assets list (id, filename, date).

Предоставляет доступ к библиотеке этого аккаунта другому пользователю на сервере. Другой пользователь увидит эти фотографии рядом со своими. Идентификатор можно найти с помощью list_users. Побочный эффект: предоставляет пользователю доступ на чтение ко всей библиотеке. Аргументы: user_id: пользователь, с которым нужно поделиться. Возвращает: JSON с новой записью партнёра.

Создаёт публичную общую ссылку для альбома и делает его доступным по URL без аутентификации. Используется для публикации галереи для внешнего просмотра.Побочный эффект: создаётся общедоступный URL. Аргументы:album_id: UUID альбома, который нужно опубликовать.allow_download: Разрешить посетителям скачивать исходные файлы (по умолчанию true).show_metadata: Показывать посетителям EXIF-данные (по умолчанию true).description: Необязательное читаемое описание для ссылки. Возвращает: JSON с идентификатором ссылки, ключом, идентификатором альбома и полным общедоступным URL.

Group near-identical assets (a burst, retries of the same shot) into one stack. The library then shows the stack as a single item fronted by its primary asset, which keeps every shot without the visual clutter — a gentler cleanup than deleting. The first id becomes the primary. Side effect: creates the stack on the server. Args: asset_ids: The assets to group, at least two. Order matters: the first is the cover. Returns: JSON with the new stack's id, primary_asset_id and asset list.

Создаёт новый тег для категоризации ресурсов. Сначала используйте list_tags, чтобы избежать дубликатов. Побочный эффект: создаёт новый тег в Immich. Аргументы: name: Отображаемое имя тега (например 'Vacation', 'Family', 'Work'). Должно быть уникальным. color: Необязательный hex-цвет для тега (например '#FF5733'). Возвращает: JSON с id, name и color нового тега.

Удаляет один комментарий или лайк. Побочный эффект: удаляет его для всех. Аргументы: activity_id: активность, которую нужно удалить (из list_activities). Возвращает: JSON, подтверждающий удаление.

Delete an album container. The photos inside are NOT deleted — they remain in the library. Use this to remove unwanted album groupings. Side effect: permanently deletes the album (cannot be undone). Args: album_id: The album's UUID to delete. Returns: JSON with success, the deleted album's id and album_id.

Удаляет активы (мягкое удаление в корзину или безвозвратное). Используйте для удаления ненужных фотографий/видео. По умолчанию — мягкое удаление (восстанавливается через restore_assets). При force=true удаление НАВСЕГДА и НЕОБРАТИМО. Побочный эффект: перемещает/удаляет активы. Аргументы: asset_ids: Список UUID активов для удаления. force: false (по умолчанию) = перемещение в корзину (восстанавливаемо). true = удаление НАВСЕГДА (без отмены). Возвращает: JSON с количеством удалённых и указанием, использовался ли force.

Удаляет память. Фотографии остаются в библиотеке, удаляется только запись памяти. Побочный эффект: удаляет память с сервера. Аргументы: memory_id: Память, которую нужно удалить. Возвращает: JSON с подтверждением удаления.

Удаляет (отзывает) общую ссылку, делая публичный URL немедленно недоступным. Альбом и его фотографии не затрагиваются. Побочный эффект: навсегда удаляет ссылку. Аргументы: link_id: UUID общей ссылки для удаления. Возвращает: JSON с подтверждением удаления и link_id.

Расформировывает стек. Активы НЕ удаляются - они просто снова отображаются как отдельные элементы. Побочный эффект: удаляет группировку на сервере. Аргументы: stack_id: стек, который нужно расформировать. Возвращает: JSON, подтверждающий удаление.

Delete a tag and remove it from all assets. The assets themselves are unaffected. Side effect: permanently deletes the tag (cannot be undone). Args: tag_id: The tag's UUID to delete. Returns: JSON with success, the deleted tag's id and tag_id.

Download an album or a selection as one zip of the original files, written to a local path. Use get_download_info first when the size matters. The file is streamed to disk (safe for big albums) and an existing file is never overwritten. Side effect: writes a file on the machine running the server. Args: output_path: Where to write the zip (an existing file is refused). album_id: Download the whole album. asset_ids: Or download just these assets. Returns: JSON with path, bytes written and how many assets went in, or an error.

Удаляет навсегда ВСЕ ресурсы, находящиеся в корзине. РАЗРУШИТЕЛЬНО и НЕОБРАТИМО. Используйте это только после подтверждения, что пользователь хочет очистить все удалённые элементы. Для удаления конкретных ресурсов используйте delete_assets. Побочный эффект: навсегда уничтожает все удалённые ресурсы и освобождает хранилище. Возвращает: JSON с подтверждением успеха.

Создаёт PDF (обложка, оглавление, места, по одному разделу на актив) из альбома или списка активов на машине, где работает этот сервер. Всегда включает метаданные Immich (дата, место, камера, люди, теги); передавайте captions {asset_id: текст} с тем, что вы увидели, чтобы добавить свой анализ. Кадры видео попадают сразу в PDF и не расходуют токены (до 120 на видео). PDF никогда не попадает в диалог, если только return_base64=True. Если пользователь запросил PDF, не уточнив, как его оформить, сначала вызовите get_export_preview и спросите его о вариантах, которые он перечисляет. Следите, чтобы подборка была цельной: один сюжет на PDF. Никогда не смешивайте несвязанные активы (два видео о разных вещах, фото с разных событий) только ради того, чтобы показать больше; если материал пользователя охватывает несколько сюжетов, предложите вместо этого отдельный PDF для каждого сюжета. Аргументы: album_id: UUID альбома, или asset_ids: явные UUID активов (ровно один из двух). output_path: куда сохранять (по умолчанию ~/Desktop/<title>.pdf). Не перезаписывает существующие файлы. title: заголовок обложки (по умолчанию: название альбома или «Immich export <дата>»). captions: {asset_id: текст}, пишутся после просмотра изображений. layout: 'detail' (по одному активу на страницу с его данными, по умолчанию), 'grid' (по шесть на страницу) или 'photobook' (по одному активу на страницу, изображение максимально большого размера, подпись под ним; видео с несколькими выбранными кадрами разворачивается в одну полную страницу на каждый кадр). frames_per_video: количество кадров на видео, равномерно распределённых (0-120, по умолчанию 4; 0 = только постер). frame_interval: один кадр каждые N секунд вместо frames_per_video (тот же лимит 120). frame_times: {asset_id: [секунды, ...]} точные моменты для конкретных видео, выбранные после просмотра их кадров («показательный кадр»). Для указанных видео имеет приоритет над frames_per_video/frame_interval; остальные сохраняют равномерное распределение. frame_captions: {asset_id: [текст, ...]} одна подпись на каждый извлечённый кадр, в порядке кадров (photobook печатает каждую на странице своего кадра; остальные макеты их игнорируют).

Получает полные сведения о конкретном альбоме, включая все идентификаторы его ресурсов. Используйте его, чтобы просмотреть содержимое альбома или получить идентификаторы ресурсов для дальнейших операций (миниатюры, метаданные, поворот). Для вывода списка всех альбомов используйте вместо этого list_albums. Только чтение. Аргументы: album_id: UUID альбома (из list_albums или create_album). Возвращает: JSON с метаданными альбома, плоский список всех asset_ids и массив assets (id, filename, type, date, recognized people), чтобы на вопрос «кто появляется в этом альбоме / кто повторяется» можно было ответить без дополнительных вызовов.

Получает миниатюры альбома в виде блоков изображений для встроенного визуального отображения. Используйте этот инструмент для визуального просмотра альбома в клиентах, которые отображают изображения. Для генерации HTML-галереи с base64 data URIs (Cowork/skills) используйте вместо этого get_album_thumbnails: он возвращает JSON с именами файлов и датами. Только чтение. Args: album_id: UUID альбома. size: 'thumbnail' (250px) или 'preview' (1440px). По умолчанию: 'thumbnail'. limit: Максимальное количество миниатюр для возврата (1-50, по умолчанию 20). Возвращает: список блоков изображений, подходящих для визуального отображения.

Получает миниатюры фотографий из альбома в кодировке base64. Используйте это, чтобы создавать визуальные HTML-галереи из существующего альбома. Для миниатюр из результатов поиска (без альбома) используйте get_thumbnails_batch. Только для чтения. Аргументы: album_id: UUID альбома. size: 'thumbnail' (250px) или 'preview' (1440px). По умолчанию: 'thumbnail'. limit: Максимум миниатюр к возврату (1-50, по умолчанию 20). Возвращает: JSON с информацией об альбоме и массивом миниатюр (каждая содержит asset_id, данные base64, имя файла, дату).

Получает все обнаруженные лица на фотографии с их привязкой к людям. Используйте это, чтобы увидеть, кто на конкретном фото, или найти ID лиц для reassign_face. Только для чтения. Аргументы: asset_id: UUID ресурса. Возвращает: JSON-массив обнаружений лиц (каждое содержит face_id, person_id, person_name, bounding box).

Получает миниатюру одного ресурса в виде блока изображения для встроенного визуального отображения. Используйте это в клиентах, которые отображают изображения (Open WebUI, Claude Desktop). Для генерации HTML-галереи с base64 data URI (Cowork/skills) используйте вместо этого get_asset_thumbnail, он возвращает JSON. Только чтение. Аргументы: asset_id: UUID ресурса. size: 'thumbnail' (250px, быстро) или 'preview' (1440px, более высокое качество). По умолчанию: 'thumbnail'. Возвращает: блок изображения (MCP ImageContent) для визуального отображения.

Get full metadata for a single asset. Use this when you need EXIF details, GPS coordinates, camera info, or file properties for a known asset ID. For finding assets, use search_metadata or search_smart instead. Read-only. Args: asset_id: The asset's UUID (from search results, album listings, or list_assets). with_notes: Also include the plugin's notes on the asset (past review verdicts and recorded actions, see get_asset_notes). One extra request. Returns: JSON with EXIF data, GPS, dates, dimensions, file size, camera make/model, and owner; plus a notes object (reviews and actions) when with_notes is true.

The plugin's notes on one asset: past review verdicts with reasons and recorded actions, newest last. Empty lists when it was never annotated. Read-only. Args: asset_id: The asset to read. Returns: JSON with asset_id, reviews [{at, verdict, reason}] and actions [{at, action, detail}].

Which of these assets already carry notes, and their last verdict — the call that lets a cleanup pass skip what an earlier session reviewed. Immich cannot search this metadata, so the server is asked once per asset (no tokens spent on the ones without notes). Read-only. Args: asset_ids: The candidates to check (an album's assets, a search result). Returns: JSON with checked (how many were asked), annotated (one compact row per asset that has notes — asset_id, last_verdict, last_reason, last_review_at, and the reviews/actions counts) and a failed array of {asset_id, error} for the assets that could not be read. Success is true only when nothing failed.

Получает изображение миниатюры в кодировке base64 для одного ресурса. Используйте это для визуального просмотра одного фото. Для нескольких фото используйте get_thumbnails_batch (по ID) или get_album_thumbnails (по альбому). Только чтение. Аргументы: asset_id: UUID ресурса. size: 'thumbnail' (250px, быстро) или 'preview' (1440px, более высокое качество). По умолчанию: 'thumbnail'. Возвращает: JSON с полями 'data' (строка в base64) и 'type' (MIME-тип, например 'image/jpeg').

How many photos per day, over a date range — the data behind a calendar heatmap. Use this to find gaps (months with nothing), busy periods, or to check a library's health at a glance without listing assets. Immich 3.x answers natively; on Immich 2.x the same shape is built from the timeline (taken dates only), which costs one request per month in the range, so pass the narrowest range that answers the question. Read-only. Args: from_date: ISO date lower bound (e.g. '2026-01-01'). Omit for the server default on Immich 3.x; on 2.x an omitted bound means the last 365 days, because an open-ended range would walk every month of the library. to_date: ISO date upper bound. Omit for the server default. heatmap_type: 'Taken' (capture date, default) or 'Upload' (when it reached Immich; 3.x only). Returns: JSON with source ('immich' or 'timeline'), total and a series of {date, count} for the days that have activity, oldest first (a day missing from the series had nothing).

What this Immich server can do: version, feature flags and known quirks. Use this once at the start of a session to learn whether OCR, smart search or facial recognition are available before offering them, and which behaviours differ between Immich 2.x and 3.x. Read-only. Returns: JSON with server_version, immich_major, features (the server's own flags: ocr, smartSearch, facialRecognition, map, trash...) and quirks (plain sentences about version-specific behaviour the caller should know). When the API key may not read the feature flags, features is empty and a note says so; the version and the quirks still come back.

Возвращает базовый URL Immich и маскированный ключ API. Использует это для заполнения заполнителей шаблона галереи (например, {{IMMICH_URL}}). Ключ API намеренно замаскирован в целях безопасности — миниатюры используют data URI в формате base64, а не прямые вызовы API. Только чтение. Возвращает: JSON с полями base_url и api_key_masked (только первые 8 и последние 4 символа).

Определяет, насколько большим будет ZIP-архив альбома или выборки, ДО его создания. Используйте это, чтобы предупредить пользователя о размере (оригиналы и видео быстро набирают объём), а затем решить, вызывать ли download_archive. Только чтение. Аргументы: album_id: вычисляет размер всего альбома. asset_ids: или вычисляет размер только этих ресурсов. Возвращает: JSON с total_size_mb, asset_count и количеством архивов, на которые Immich разобьёт загрузку.

Получает группы дубликатов, обнаруженные ML-сервисом (одинаковые изображения, сохранённые более одного раза). Используйте этот инструмент для проверки потенциальных дубликатов перед их разрешением через resolve_duplicates. Требуется ML-сервис Immich. Примечание: «duplicates» означает одну и ту же фотографию, а не одного человека; для поиска людей используйте get_album (assets[].people) или get_asset_faces. Только для чтения. Параметры: album_id: Необязательный. Ограничивает выбор группами, которые затрагивают этот альбом; каждая группа также сообщает, какие из её ресурсов находятся внутри или снаружи альбома. Возвращает: JSON-массив групп дубликатов (каждая с duplicateId, массивом assets и оценками сходства).

Перечисляет, что включит export_pdf (id, type, filename, date, place, people, video duration), чтобы вы знали, какие активы существуют, прежде чем смотреть на изображения и писать подписи. Передавайте ровно один из параметров album_id / asset_ids. Только чтение. Результат также содержит options: каждый вариант, который принимает export_pdf, со значением по умолчанию. Когда пользователь запросил PDF, не уточнив, как его оформить, покажите ему эти варианты и спросите (макет, титульные страницы, какие моменты видео, подписи) перед экспортом; если он задал параметры или просто хочет «PDF, стандартные настройки подойдут», экспортируйте сразу. Аргументы: album_id: UUID альбома, или asset_ids: явные UUID активов (результаты поиска, выборка). limit: максимум активов (1-500, по умолчанию 100). Возвращает: JSON {title, count, assets:[...], warnings:[...]} или {"error": ...}.

Получает миниатюры для произвольных ID ресурсов в виде блоков изображений для встроенного визуального отображения. Используйте этот инструмент, чтобы визуально показывать результаты поиска в клиентах, которые отображают изображения. Чтобы создавать HTML-галереи с base64 data URI (Cowork/skills), используйте get_thumbnails_batch - он возвращает JSON с именами файлов и датами. Только чтение. Аргументы: asset_ids: список UUID ресурсов, для которых нужно получить миниатюры. size: 'thumbnail' (250px) или 'preview' (1440px). По умолчанию: 'thumbnail'. limit: максимум возвращаемых миниатюр (1-50, по умолчанию 20). Получаются только первые N ID. Возвращает: список блоков изображений, подходящих для визуального отображения.

Получает GPS-маркеры на карте для всех геотегированных ресурсов. Используйте это, чтобы узнать, где были сделаны фотографии, или для построения карт путешествий. Для поиска по названию города/страны используйте search_metadata вместо этого. Только для чтения. Возвращает до 500 маркеров. Аргументы: file_created_after: Нижняя граница даты в формате ISO (например, '2023-01-01'). file_created_before: Верхняя граница даты в формате ISO. is_favorite: Если true, возвращает только избранные. Возвращает: JSON с общим количеством и массивом маркеров (каждый с идентификатором ресурса, широтой, долготой).

Получает полную информацию о конкретном человеке, включая имя, дату рождения и количество фотографий. Используйте после того, как найдете человека через list_people или search_people. Только для чтения. Args: person_id: UUID человека (из list_people или search_people). Returns: JSON с информацией о человеке (id, name, birthDate, isHidden, photoCount, thumbnailPath).

Получает миниатюру лица в формате base64 для человека. Используйте её для визуального определения личности перед объединением или переименованием. Только чтение. Аргументы: person_id: UUID человека. Возвращает: JSON с полями 'data' (строка base64 части лица) и 'type' (MIME-тип).

Получает версию сервера Immich. Используйте это для проверки совместимости или чтобы сообщить работающую версию сервера. Только для чтения. Возвращает: JSON с номерами версий major, minor и patch.

Получает полные сведения об общей ссылке, включая разрешения, срок действия и связанные ресурсы. Проверяет конфигурацию конкретной ссылки. Только для чтения. Аргументы: link_id: UUID общей ссылки (из list_shared_links). Возвращает: JSON со сведениями о ссылке, разрешениями, датой истечения срока действия и связанными ресурсами/альбомом.

One stack with its assets. Use this after list_stacks to see everything a group holds before changing its cover or dissolving it, or to check what create_stack actually grouped. Read-only. Args: stack_id: The stack to fetch. Returns: JSON with id, primary_asset_id and the asset list.

Получает статистику библиотеки. Используйте для быстрого обзора размера библиотеки без перечисления отдельных ресурсов. Только чтение. Возвращает: JSON с общим количеством фотографий, видео и объёмом хранилища в байтах.

Получает детали о конкретном теге. Используйте этот инструмент, чтобы просмотреть свойства тега. Только чтение. Аргументы: tag_id: UUID тега (из list_tags). Возвращает: JSON с id тега, именем, цветом и количеством использований.

Получает миниатюры в кодировке base64 для произвольных идентификаторов ресурсов без необходимости в альбоме. Используйте это для визуального отображения результатов поиска или любого произвольного набора фотографий. Для миниатюр на основе альбома используйте get_album_thumbnails. Для одной фотографии используйте get_asset_thumbnail. Только для чтения. Аргументы: asset_ids: Список UUID ресурсов, для которых нужно получить миниатюры. size: 'thumbnail' (250 пикселей) или 'preview' (1440 пикселей). По умолчанию: 'thumbnail'. limit: Максимальное количество возвращаемых миниатюр (1–50, по умолчанию 20). Будет обработано только первые N идентификаторов. Возвращает: JSON с массивом миниатюр (каждая содержит asset_id, данные в base64, имя файла, дату).

Активы из одного временного bucket, полученного через get_timeline_buckets. Используйте эти два инструмента вместе, чтобы просматривать библиотеку по месяцам без дорогостоящих поисков. Только для чтения. Аргументы: time_bucket: Ключ bucket точно в том виде, в котором его вернул get_timeline_buckets (например, '2026-03-01'). album_id: Только активы из этого альбома. person_id: Только активы с этим человеком. tag_id: Только активы с этим тегом. is_favorite: Если true, только избранные. Возвращает: JSON с массивом assets; каждая запись содержит asset_id, date, is_image, is_favorite, duration, city и country.

Month-by-month map of the library: one bucket per month with its asset count. Use this before fetching assets — it shows in one cheap call which months hold photos and how many, ideal for finding gaps, busy periods, or navigating a large library without paging through everything. Read-only. Args: album_id: Only count assets in this album. person_id: Only count assets showing this person. tag_id: Only count assets carrying this tag. is_favorite: If true, only count favorites. order: 'desc' for newest month first (the default), 'asc' for oldest first. Returns: JSON with total_buckets and a buckets array of {timeBucket, count}, newest month first unless order='asc'.

Получает кадры видео в виде блоков изображений, чтобы «смотреть» клип. Immich хранит по одному постеру на видео; этот инструмент скачивает видео и извлекает кадры локально (PyAV, зависимость начиная с версии 1.7.1, или ffmpeg из PATH). Каждый кадр - это одно изображение для модели. Рабочий процесс: сначала 6 кадров; чтобы рассмотреть ближе, диапазон сужается с помощью start/end или используется интервал (до 1 с). Если кадров больше 12, инструмент возвращает JSON-план с полями frames_planned и estimated_tokens вместо изображений: план показывается пользователю, и повторный вызов с confirm=true выполняется только при его согласии. Жесткий лимит - 120 кадров на вызов. Для base64 JSON с временными метками используйте get_video_frames_json. Только для чтения. Args: asset_id: UUID видеозаписи. count: Кадры, равномерно распределённые по сегменту (по умолчанию 6). Игнорируется, если interval > 0. size: 'thumbnail' (250px, ~1.6 тыс. токенов на кадр) или 'preview' (1440px, ~6.4 тыс. токенов). По умолчанию 'thumbnail'. start: Начало сегмента в секундах (по умолчанию 0). end: Конец сегмента в секундах (0 = до конца). interval: Один кадр каждые N секунд вместо count (1 = один кадр в секунду, максимальная гранулярность). confirm: Требуется (true), если будет создано более 12 кадров; сначала спросите пользователя. sheet: Упаковывает кадры в контактные листы (30 кадров на изображение, с встроенными временными метками): длинное видео превращается в одно или два изображения вместо десятков, поэтому подтверждение не требуется. Используйте для быстрого просмотра, затем вырезайте важные моменты. Возвращает: JPEG-блоки изображений в хронологическом порядке или JSON (план подтверждения / ошибка).

Кадры видео в формате base64 JPEG с временными метками для HTML-галерей и навыков. Те же параметры, порог (подтверждение при >12) и лимит (120), что и у get_video_frames. Только чтение. Аргументы: asset_id: UUID видеоматериала. count: Кадры, равномерно распределённые по сегменту (по умолчанию 6). Игнорируется, когда interval > 0. size: 'thumbnail' (250px, ~1.6k токенов на кадр) или 'preview' (1440px, ~6.4k). По умолчанию 'thumbnail'. start: Начало сегмента в секундах (по умолчанию 0). end: Конец сегмента в секундах (0 = до конца). interval: Один кадр каждые N секунд вместо count (1 = один раз в секунду, максимальная детализация). confirm: Обязателен (true), если будет создано более 12 кадров; сначала спросите пользователя. Возвращает: JSON {asset_id, duration, backend, count, frames:[{timestamp, data, type}]}, план подтверждения {confirm_required, frames_planned, estimated_tokens, ...} или {"error": ...}.

Comments and likes on a shared album, newest context included. Use this to read what the people an album is shared with have said about it or about one of its photos. Read-only. Args: album_id: The album whose activity to read. asset_id: Only activity on this asset within the album. activity_type: 'comment' or 'like'. Omit for both. Returns: JSON with total and an activities array (id, type, comment, asset_id, user name, created_at).

Перечисляет все альбомы в библиотеке с краткой информацией. Используйте эту возможность, чтобы узнать о существующих альбомах перед созданием новых или для поиска ID альбома. Только для чтения. Аргументы: shared: true = только общие альбомы, false = только не общие, опустить = все альбомы. Возвращает: JSON с общим количеством и массивом альбомов (каждый содержит id, name, description, assetCount, статус shared).

Перечисляет активы с простыми фильтрами (поисковый запрос не требуется). Используйте это для просмотра библиотеки по статусу (избранное, архив, корзина) или типу. Для поиска конкретного содержимого используйте search_metadata (структурированный) или search_smart (визуальный ИИ). Только для чтения. Аргументы: is_favorite: true = только избранные, false = только неизбранные, не указывать = все. is_archived: true = только архивные, false = только не архивные, не указывать = все. is_trashed: true = только элементы в корзине; false/не указывать = активная библиотека (Immich никогда не смешивает оба состояния). asset_type: 'IMAGE' или 'VIDEO'. Не указывать = оба. page: Номер страницы, начиная с 1 (по умолчанию 1). size: Количество результатов на странице (1-200, по умолчанию 50). Возвращает: JSON с общим количеством, текущей страницей и массивом активов с идентификаторами, именами файлов, датами и типами.

List memories — Immich's "on this day" collections of photos from past years. Use this to build a 'tal día como hoy' story, album or PDF: each memory carries the year it looks back to and the assets Immich picked for it. Read-only. Args: for_date: ISO date — return the memories Immich shows on that day (e.g. today for the classic on-this-day feed). Omit for all memories. is_saved: If true, only memories the user saved; if false, only unsaved. size: Maximum memories to return (default 50). Returns: JSON with total and a memories array; each has id, type, memory_at, the year it remembers, is_saved, asset_count and a trimmed assets list (id, filename, date).

Кто делится своей библиотекой с этим аккаунтом, и с кеми этот аккаунт делится своей. Совместный доступ с партнёром — это семейная функция Immich: каждая сторона сохраняет свою библиотеку, но может видеть библиотеку другой. Только чтение. Возвращает: JSON с массивами shared_with_me и shared_by_me (id, name, email, in_timeline).

Перечисляет всех распознанных людей (кластеры лиц) в библиотеке. Используйте это, чтобы просмотреть, кто изображён в фототеке, или найти ID человека. Для поиска по имени используйте search_people. Только чтение. Аргументы: page: номер страницы, начиная с 1 (по умолчанию 1). size: количество результатов на странице (по умолчанию 50). with_hidden: включать людей, отмеченных как скрытые (по умолчанию false). Возвращает: JSON с общим количеством (total count), страницей (page) и массивом людей (people), каждый из которых содержит id, name, thumbnailPath, photoCount.

Выводит список всех общих ссылок (публичных URL-адресов галереи). Используйте для просмотра того, что в данный момент опубликовано, или для поиска ID ссылки для обновления/удаления. Только чтение. Возвращает: JSON с общим количеством и массивом ссылок (каждая содержит id, key, type, description, album info).

Перечисляет все стеки в библиотеке. Используйте это, чтобы увидеть, что уже сгруппировано, перед созданием новых стеков или чтобы найти идентификатор стека. Только для чтения. Args: primary_asset_id: Только стек, начинающийся с этого актива. Returns: JSON с полем total и массивом stacks (id, primary_asset_id, assets).

Перечисляет все теги в библиотеке. Используйте это, чтобы найти существующие теги перед созданием новых или получить ID тега для операций тегирования. Только для чтения. Возвращает: JSON с общим количеством и массивом тегов (каждый содержит id, name, color).

The users visible on this Immich server. Use this to find the id that create_partner needs, or to see who could be shared with. Read-only. Returns: JSON with total and a users array of {id, name, email}.

Merge multiple person clusters into one. Use this when the same real person has been split into multiple face clusters. DESTRUCTIVE and IRREVERSIBLE: merged persons are permanently deleted and all their faces transfer to the target. Without confirm=true nothing happens: the call returns who would be kept and who would disappear, so the user can check the names before the merge. Side effect: with confirm=true, permanently deletes the merged persons; without it the call only previews and changes nothing. Args: person_id: The target person UUID to keep (receives all merged faces). merge_ids: List of person UUIDs to absorb into the target. These persons are permanently deleted. confirm: Pass true only after the user has seen the preview and agreed. Returns: JSON with the preview (confirm_required, keep, merge, failed) or the merge result.

Проверяет соединение с сервером Immich. Используйте для проверки доступности сервера перед выполнением других операций. Только чтение. Возвращает: JSON со статусом 'server' ('pong' если здоров).

Переназначает обнаруженное лицо другому человеку. Используйте для исправления ошибок распознавания лиц (например, лицо, ошибочно приписанное лицу А, должно быть лицом Б). Сначала получите face_id через get_asset_faces. Побочный эффект: навсегда изменяет связь лицо-человек. Аргументы: face_id: UUID обнаружения лица (из результатов get_asset_faces). person_id: UUID правильного человека, которому нужно назначить это лицо. Возвращает: JSON с обновлённым назначением лица.

Remember something the plugin did to assets and why, for audit or undo: which album they went into and from what prompt, what date they had before a fix, why they were rotated. Side effect: writes the plugin's metadata key on each asset; other apps' keys are untouched. Args: asset_ids: The assets the action touched. action: Short verb-like label (e.g. 'added_to_album', 'date_fixed', 'rotated'). detail: Free text with the context worth keeping (album name, previous value, the user's request). Returns: JSON with success, the number of assets recorded, the action, and a failed array of {asset_id, error} for any asset that could not be written. Success is true only when nothing failed.

Удаляет активы из альбома, не удаляя их сами. Фотографии остаются в библиотеке и других альбомах. Используйте это, чтобы отменить курирование ошибочно добавленных активов. Побочный эффект: изменяет состав альбома. Аргументы: album_id: UUID альбома, из которого нужно удалить активы. asset_ids: Список UUID активов, которые нужно удалить из этого альбома. Возвращает: JSON с album_id, количеством удалённых и деталями результата по каждому активу.

Прекращает предоставление доступа к библиотеке этого аккаунта пользователю. Собственные фотографии пользователя не затрагиваются. Побочный эффект: отзыв доступа. Аргументы: user_id — идентификатор пользователя, которому прекращается доступ. Возвращает: JSON, подтверждающий удаление доступа.

Разрешает дубликаты групп, выбирая, какие ассеты оставить, а какие отправить в корзину. Используйте этот инструмент после просмотра результатов get_duplicates. Ассеты в корзине можно восстановить через restore_assets. Побочный эффект: перемещает отклонённые дубликаты в корзину. Аргументы: groups: Список словарей, каждый с полями: duplicateId (из get_duplicates), assetIds (UUID для СОХРАНЕНИЯ), trashIds (UUID для УДАЛЕНИЯ). Возвращает: JSON с количеством разрешённых групп.

Восстанавливает конкретные активы из корзины обратно в активную библиотеку. Используйте этот инструмент для выборочного восстановления случайно удалённых фотографий. Для восстановления всего сразу используйте restore_trash. Побочный эффект: перемещает указанные активы из корзины. Аргументы: asset_ids: список UUID активов, находящихся в корзине, которые нужно восстановить. Возвращает: JSON с количеством восстановленных активов.

Восстанавливает ВСЕ удалённые активы обратно в библиотеку. Используйте это, чтобы отменить случайное массовое удаление. Для восстановления только определённых активов используйте restore_assets. Побочный эффект: перемещает все удалённые активы обратно в активную библиотеку. Возвращает: JSON с подтверждением успеха.

Resolve GPS coordinates to a place name using Immich's own offline geodata. Use this to name the location of a marker from get_map_markers or of an asset's EXIF coordinates — no external service is contacted. Read-only. Args: lat: Latitude in decimal degrees. lon: Longitude in decimal degrees. Returns: JSON with total and a places array of {city, state, country} candidates.

Удаляет все недеструктивные изменения (поворот, кадрирование, отражение) из активов, восстанавливая исходный вид. Используйте это, чтобы отменить rotate_assets или любые другие преобразования отображения. Укажите ЛИБО asset_ids, ЛИБО album_id. Побочный эффект: удаляет все записи правок для активов. Аргументы: asset_ids: Список UUID активов для восстановления. Взаимоисключающе с album_id. album_id: Восстанавливает все активы в этом альбоме. Взаимоисключающе с asset_ids. Возвращает: JSON с количеством восстановленных и неудавшихся операций.

Remember a review verdict on assets, with the reason, so a later session does not redo the analysis and the why survives. Use this after deciding what to do with a photo in a cleanup or duplicate pass — together with a tag when the user must see the state in Immich (tags are visible there, notes are not). Side effect: writes the plugin's metadata key on each asset; other apps' keys are untouched. Args: asset_ids: The assets the verdict applies to. verdict: One of 'keep', 'delete_candidate', 'duplicate_of', 'needs_check'. reason: Free text explaining the verdict (e.g. 'near-identical to IMG_6367, keep that one'). Short and concrete beats long. Returns: JSON with success, the number of assets reviewed, the verdict, and a failed array of {asset_id, error} for any asset that could not be written. Success is true only when nothing failed.

Применяет неразрушающий поворот по часовой стрелке к одному или нескольким активам. Используйте это для исправления проблем с ориентацией. Исходный файл никогда не изменяется — поворот только меняет отображение. Используйте revert_asset_edits для отмены. Укажите ЛИБО asset_ids, ЛИБО album_id. Побочный эффект: записывает правки поворота в Immich; накапливается с существующим поворотом. Args: angle: градусы по часовой стрелке, должно быть кратно 90 (90, 180 или 270). По умолчанию: 90. asset_ids: список UUID активов для поворота. Взаимоисключающие с album_id. album_id: повернуть все активы в этом альбоме. Взаимоисключающие с asset_ids. Возвращает: JSON с количеством повёрнутых/неудачных и применённым углом.

Каждый город, представленный в библиотеке, по одному репрезентативному ассету на каждый. В отличие от search_explore, здесь нет минимального порога по количеству ассетов, поэтому это надёжный способ ответить на вопрос «какие места есть в этой библиотеке?». Только чтение. Возвращает: JSON с массивом cities в формате {city, country, asset_id, date}.

Overview of what the library contains, grouped by explore field: one representative asset per city and per detected concept (Immich's Explore page). Use this to get oriented in an unknown library before searching for anything specific — it answers 'what is in here?' in one call. A city only appears once it holds at least 5 assets (Immich's own threshold), so small libraries can come back empty. Read-only. Returns: JSON with total (how many fields came back) and a fields array; each field has its name (e.g. 'exifInfo.city') and items pairing each value with one representative asset_id.

The biggest files in the library, largest first. Use this to find what is eating storage before a cleanup — videos and originals show up immediately. Read-only. Args: min_size_mb: Only assets at least this many megabytes (0 = no minimum). size: How many assets to return (1-200, default 20). asset_type: 'IMAGE' or 'VIDEO'. Omit for both. Returns: JSON with total and an assets array of {asset_id, filename, size_mb, date}, largest first.

Search assets by EXIF metadata fields. Use this when you know specific criteria like city, camera model, or date range. For natural language visual queries (e.g. 'sunset at the beach'), use search_smart instead. For browsing without criteria, use list_assets. Read-only. Args: city: City name from EXIF GPS reverse-geocoding (case-sensitive, e.g. 'Barcelona'). state: State or region name. country: Country name (e.g. 'Spain', 'Egypt'). make: Camera manufacturer (e.g. 'Apple', 'Canon', 'Sony'). model: Camera model string (e.g. 'iPhone 14 Pro', 'EOS R5'). taken_after: ISO date — return only assets captured after this date. taken_before: ISO date — return only assets captured before this date. is_favorite: If true, only return favorites. asset_type: 'IMAGE' or 'VIDEO'. Omit for both. ocr: Text recognized inside the image (tickets, signs, documents). Needs OCR enabled on the server — check with get_capabilities. person_ids: Only assets showing ALL of these people (ids from list_people). tag_ids: Only assets carrying these tags (ids from list_tags). album_ids: Only assets inside these albums. page: Page number, starting from 1 (default 1). size: Results per page (1-200, default 50). Returns: JSON with total match count, current page, and assets array with IDs, filenames, and dates.

Ищет людей по имени (частичное совпадение). Используйте этот инструмент, когда знаете имя человека. Для просмотра всех людей используйте list_people. Только чтение. Аргументы: name: Полное или частичное имя для поиска (без учёта регистра). with_hidden: Включает скрытых людей в результаты (по умолчанию false). Возвращает: JSON-массив подходящих людей с полями id, name и photo count.

Ищет название места во встроенном справочнике географических названий Immich (без участия ресурсов). Используйте этот инструмент, чтобы уточнить написание или получить координаты места перед географическим поиском. Только чтение. Аргументы: name: Название места для поиска (например, 'Lisbon'). Возвращает: JSON с массивом places, содержащим элементы {name, admin1name, admin2name, latitude, longitude}.

Возвращает случайные активы из библиотеки, с возможностью фильтрации. Используйте это для выборки - быстрой оценки того, что соответствует фильтру, неожиданного выбора для истории или точечных проверок по большой библиотеке. Только чтение. Аргументы: size: Сколько случайных активов вернуть (по умолчанию 10, максимум 100). city: Только активы из этого города. country: Только активы из этой страны. make: Только активы этого производителя камер. model: Только активы этой модели камеры. is_favorite: Если true, только избранные. ocr: Только активы, у которых распознанный текст совпадает (требует OCR на сервере). Возвращает: JSON с массивом подходящих активов.

AI-powered visual search using CLIP embeddings. Use this when describing what a photo looks like in natural language (e.g. 'sunset at the beach', 'dog playing fetch'). For structured criteria (city, camera, date), use search_metadata instead. Requires Immich ML service with Smart Search enabled. Read-only. Args: query: Natural language description of the visual content to find. city: Optional city filter to narrow results geographically. state: Optional state/region filter. country: Optional country filter. taken_after: ISO date — only assets captured after this date. taken_before: ISO date — only assets captured before this date. ocr: Text recognized inside the image, combined with the visual query. Needs OCR enabled on the server — check with get_capabilities. person_ids: Only assets showing ALL of these people (ids from list_people). tag_ids: Only assets carrying these tags (ids from list_tags). album_ids: Only assets inside these albums. page: Page number, starting from 1 (default 1). size: Results per page (1-200, default 50). Returns: JSON with total count, page, and assets ranked by visual similarity to the query.

Count how many assets match a filter WITHOUT fetching them. Use this instead of search_metadata whenever only the number matters ('how many photos from Spain?', 'how many did I take in 2019?') — it costs one integer instead of pages of assets. Read-only. Args: city: Count assets from this city. country: Count assets from this country. state: Count assets from this state/region. make: Count assets from this camera make. model: Count assets from this camera model. is_favorite: If true, count only favorites. ocr: Count assets whose recognized text matches (needs OCR on the server). created_after: ISO date lower bound on upload date (when it reached Immich). created_before: ISO date upper bound on upload date. taken_after: ISO date lower bound on capture date (when the photo was taken). taken_before: ISO date upper bound on capture date. Returns: JSON {total}.

Distinct values present in the library for one field — the exact spellings search_metadata expects. Use this before filtering by city or camera to avoid guessing (e.g. 'iPhone 14 Pro' vs 'iPhone14,3'). Read-only. Args: suggestion_type: One of 'country', 'state', 'city', 'camera-make', 'camera-model', 'camera-lens-model'. country: Narrow city/state suggestions to this country. state: Narrow city suggestions to this state. make: Narrow model suggestions to this camera make. model: Narrow lens suggestions to this camera model. Returns: JSON with total and a suggestions array of strings.

Применяет тег к нескольким ресурсам одновременно. Используйте это для массовой категоризации фотографий (например, отметить все фотографии с отпуска). Побочный эффект: добавляет связь тега с ресурсами. Аргументы: tag_id: UUID тега для применения (из list_tags или create_tag). asset_ids: Список UUID ресурсов для тегирования. Не должен быть пустым. Возвращает: JSON с tag_id, количество тегированных и результаты по каждому ресурсу.

Удаляет тег из нескольких активов. Сам тег остаётся; удаляется только связь. Побочный эффект: удаляет связи тега с активами. Аргументы: tag_id: UUID тега, который нужно удалить из активов. asset_ids: Список UUID активов, с которых нужно снять тег. Не может быть пустым. Возвращает: JSON с tag_id, количеством снятых тегов и результатами по каждому активу.

Обновляет название или описание альбома. Используйте это, чтобы переименовать или изменить описание существующего альбома. Побочный эффект: изменяет метаданные альбома в Immich. Аргументы: album_id: UUID альбома. name: Новое название альбома. Оставьте пустым, чтобы сохранить текущее название. description: Новое описание. Оставьте пустым, чтобы сохранить текущее описание. Возвращает: JSON с обновлённым объектом альбома.

Update metadata fields on a specific asset. Use this to fix dates, correct GPS, add descriptions, or change favorite/rating status. Only provided fields are modified. Side effect: permanently changes asset metadata in Immich. Args: asset_id: The asset's UUID. date_time_original: ISO 8601 datetime (e.g. '2019-07-14T15:23:41.000Z'). latitude: GPS latitude, decimal degrees (-90.0 to 90.0). longitude: GPS longitude, decimal degrees (-180.0 to 180.0). description: Free-text description/caption for the asset. is_favorite: Set favorite status (true/false). rating: -1 to reject the photo, or 1 to 5 stars. A rating cannot be cleared from here, and 0 is not a rating Immich 3.x accepts. Returns: JSON with the updated asset object.

Update the same metadata fields on many assets in ONE call — the whole roll of a scanned album gets its real date, a trip's photos get their GPS, a selection becomes favorites. Same fields as update_asset_metadata; only the provided ones change. Side effect: permanently changes the metadata of every listed asset. Args: asset_ids: The assets to update. date_time_original: ISO 8601 datetime applied to all of them. latitude: GPS latitude, decimal degrees. longitude: GPS longitude, decimal degrees. description: Description/caption applied to all of them. is_favorite: Set favorite status on all of them. rating: -1 to reject them, or 1 to 5 stars. A rating cannot be cleared from here, and 0 is not a rating Immich 3.x accepts. Returns: JSON with success and the number of assets updated.

Обновляет учётные данные подключения к Immich. Используйте это, когда API-ключ был сменён или изменился URL сервера. Проверяет учётные данные перед применением. Побочный эффект: сохраняет новые учётные данные на диск и заменяет активное подключение без перезапуска. Параметры: base_url: Полный URL сервера Immich, включая протокол (например, 'https://photos.example.com'). api_key: Действительный API-ключ Immich (создаётся в Immich > Настройки пользователя > API-ключи). Возвращает: JSON с статусом успеха, количеством фото/видео, подтверждающим доступ, и путём сохранения.

Обновляет воспоминание: сохраняет его на потом, переносит его дату или отмечает как просмотренное. Побочный эффект: изменяет воспоминание на сервере. Аргументы: memory_id: воспоминание, которое нужно обновить. is_saved: true, чтобы сохранить воспоминание, false, чтобы отменить сохранение. memory_at: новая дата в формате ISO, когда показать воспоминание. seen_at: временная метка ISO, отмечающая, когда пользователь просмотрел его. Возвращает: JSON с обновлённым воспоминанием.

Показывает или скрывает фотографии партнёра в основной ленте (они остаются доступными в любом случае). Работает только для партнёра, который открыл доступ к своей библиотеке для этого аккаунта (то есть находится в папке «Общие со мной»), потому что этот флаг управляет тем, как фотографии этого партнёра отображаются в данной ленте. Побочный эффект: обновляет настройку на сервере. Аргументы: user_id: идентификатор партнёра, чья настройка изменяется. in_timeline: true — показывать фотографии партнёра в ленте, false — не показывать. Возвращает: JSON с обновлённой записью партнёра.

Обновляет данные профиля человека. Используйте, чтобы давать имена безымянным лицам, устанавливать даты рождения, скрывать лишние лица или менять основную миниатюру. Изменяются только указанные поля. Побочный эффект: обновляет метаданные человека в Immich. Аргументы: person_id: UUID человека. name: Отображаемое имя (например, 'Иван Петров'). Задайте имя для групп безымянных лиц. birth_date: Дата в формате ISO (например, '1990-05-15'). is_hidden: Скрыть из списка «Люди» (удобно для незнакомцев и лишних лиц). is_favorite: Отметить как избранного человека. feature_face_asset_id: UUID ресурса, чей фрагмент лица станет миниатюрой человека. color: Шестнадцатеричный цвет для группировки в интерфейсе. Возвращает: JSON с обновлённым объектом человека.

Обновляет разрешения или срок действия общей ссылки. Используйте это, чтобы усилить/ослабить доступ или установить дату истечения. Побочный эффект: немедленно изменяет поведение публичной ссылки. Аргументы: link_id: UUID общей ссылки. allow_download: Разрешает посетителям скачивать исходные файлы. show_metadata: Показывает метаданные EXIF посетителям. allow_upload: Разрешает посетителям загружать фотографии в общий альбом. description: Описание ссылки. Пустая строка очищает его. expiry_at: Дата и время истечения в формате ISO 8601. Пустая строка удаляет истечение (ссылка никогда не истекает). Возвращает: JSON с обновлённым объектом общей ссылки.

Изменяет, какой ассет находится на обложке стека (тот, который показывает библиотека). Побочный эффект: обновляет стек на сервере. Аргументы: stack_id: стек, который нужно обновить. primary_asset_id: ассет, который должен стать обложкой. Он уже должен принадлежать стеку. Возвращает: JSON с обновлённым стеком.

Обновляет цвет тега. Побочный эффект: изменения применяются ко всем ресурсам с этим тегом. API Immich не может переименовать тег (TagUpdateDto содержит только color). Чтобы переименовать, вызовите create_tag с новым именем, затем tag_assets, после чего вызовите delete_tag для старого тега. Аргументы: tag_id: UUID тега. name: не поддерживается Immich: если его передать, вернётся ошибка с объяснением обходного решения. color: новый hex-цвет (например, '#FF5733'). Не указывайте, чтобы сохранить текущий цвет. Возвращает: JSON с обновлённым объектом тега.

Загружает локальную фотографию или видеофайл в Immich. Используется для добавления новых медиафайлов в библиотеку. Ограничения: макс. 25 МБ, разрешённые типы: jpg, jpeg, png, heic, mp4, mov, gif, webp. Символические ссылки отклоняются по соображениям безопасности. Исходный файл НЕ изменяется и НЕ удаляется. Побочный эффект: создаёт новый ресурс (asset) в Immich. Аргументы: file_path: Абсолютный путь к локальному файлу (напр. '/tmp/photo.jpg'). Файл должен существовать. album_id: Необязательный UUID альбома, в который нужно сразу добавить загружаемый ресурс. Возвращает: JSON с идентификатором нового ресурса, именем файла, размером в МБ и статусом назначения альбома, если применимо.