自托管照片库智能管理助手

基于 Immich 官方 REST API 的第三方桥接工具，支持自托管照片库的上传、下载、相册管理与自动化备份，为个人及家庭用户提供私有云照片管理解决方案。

基本信息

• 技能名称?immich-api
• 中文名称?自托管照片库智能管理助手
• 作者?ninjazan420
• 分类?专业技能
• 版本?v1.0.0
• 标签?api, content-media, automation, backend, self-hosted, privacy, photo-management

使用方法

使用说明
核心用法
Immich API Bridge 是一个面向自托管 Immich 照片管理系统的 API 客户端封装工具，主要提供以下核心功能：

1. 照片资产管理 ：支持通过 REST API 上传、下载、删除照片及视频文件，可获取缩略图和原始文件
2. 相册管理 ：创建、查询、更新相册，批量添加或移除相册中的资产
3. 智能搜索 ：基于文本查询搜索照片库中的资产，支持分页返回结果
4. 用户与权限 ：查询用户信息、管理 API 密钥权限
5. 库维护 ：触发外部库扫描、查看任务队列状态、手动启动作业（如缩略图生成）
6. 自动化脚本 ：提供 upload_photos.py 、 、 download_album.py 、 、 sync_library.py 等批量操作脚本
   使用方式灵活，支持环境变量配置（ IMMICH_URL 、 、 IMMICH_API_KEY`）或 CLI 参数传入，兼容 Windows PowerShell 和 Linux/macOS bash 环境。
   显著优点
   隐私优先 ：完全对接自托管 Immich 实例，照片数据不经过第三方云服务，保障用户隐私
   功能完整 ：覆盖 Immich 核心 API 能力，从基础 CRUD 到高级搜索、作业调度一应俱全
   自动化友好 ：提供 Python 脚本封装，支持批量上传、整相册下载、库同步等高频场景
   轻量依赖 ：仅依赖 Python 标准库（ requests 、 、 argparse 、 、 pathlib 等），部署简单
   并发优化 ：下载脚本内置 5 线程并发，提升大容量相册的同步效率
   潜在缺点与局限性
   非官方维护 ：由社区开发者 ninjazan420 贡献，非 Immich 官方团队出品，长期维护存在不确定性
   功能边界 ：仅作为 API 客户端，不提供 Immich 服务端部署或配置能力
   错误处理 ：文档中未详细说明异常处理机制，网络超时、API 限流等场景需用户自行处理
   平台限制 ：脚本基于 Python 开发，Windows 用户需额外配置 Python 环境
   版本耦合 ：Immich 服务端 API 变更可能导致客户端不兼容，需关注版本匹配
   适合的目标群体
   自托管爱好者 ：已部署 Immich 实例，希望通过脚本实现照片自动化管理的用户
   家庭 NAS 用户 ：需要批量备份手机照片到私有云、定期同步相册的家庭用户
   开发者与运维 ：需要集成 Immich 照片能力到现有工作流、构建自动化备份方案的技术人员
   隐私敏感用户 ：拒绝商业云相册、坚持数据本地化的摄影爱好者
   使用风险
   API 密钥泄露风险 ： IMMICH_API_KEY 拥有照片库完全访问权限，需妥善保管，避免硬编码在共享脚本中
   网络传输安全 ：若 Immich 实例未配置 HTTPS，照片传输存在中间人攻击风险
   服务器负载 ：并发下载脚本可能对低配置 Immich 服务器造成压力，建议控制线程数或错峰操作
   数据误操作 ：批量删除、覆盖等 API 调用不可逆，建议操作前备份关键数据
   依赖可用性 ：虽当前依赖均为标准库，但未来若引入第三方包需关注供应链安全