immich-api

核心用法

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 调用不可逆，建议操作前备份关键数据
• 依赖可用性：虽当前依赖均为标准库，但未来若引入第三方包需关注供应链安全