开发者必看：利用 Immich REST API 构建你的专属自动同步工具。

作为一个硬核架构师，我极其反感那些只能通过 GUI 操作的工具。Immich 的强大之处不仅在于它的 UI 像 Google Photos，更在于它拥有一套极其成熟、完全基于 Swagger (OpenAPI) 规范的 REST API。

如果你还在手动上传照片，或者为了同步服务器上的存量资源而发愁，那说明你还没摸到 Immich 的灵魂。通过 API，你可以写几行 Python 脚本就实现“下载完成即同步”，或者构建一个自动清理重复照片的定时任务。今天，我们直接扒开 Immich 的请求头，看看如何用代码接管你的相册。

💡 架构师深度诊断：Immich API 采用 API Key 或 Bearer Token 进行鉴权。所有的上传请求本质上都是 multipart/form-data。最常见的坑在于：如果你在上传大文件（如 4K 视频）时没有正确设置请求头中的 x-immich-checksum，或者并发请求过高，API 会直接返回 413 Payload Too Large 或触发数据库锁死。

---

鉴权与协议：如何获取你的通行证？

在使用 API 之前，你需要在 Immich 管理后台的 Account Settings -> API Keys 中生成一个永久 Key。这比模拟登录拿 Cookie 要稳健得多。

所有的 API 端点默认在 /api 路径下。你可以直接访问你的服务器地址 http://your-ip:2283/api-docs 来查看完整的 Swagger 文档。但在实际开发中，有几个核心接口是每个开发者都必须掌握的：

# 典型的 API 鉴权测试
curl -X GET "http://your-ip:2283/api/server-info/statistics" \
     -H "x-api-key: your_secret_api_key"

针对不同的开发场景，我整理了一份**《Immich API 核心调用矩阵》**：

功能模块	核心 Endpoint	核心逻辑	架构师避坑点
资产上传	POST /api/assets	处理图片的二进制流、文件名和 ID	必须手动计算并传入文件 Hash，防止重复上传
智能搜索	POST /api/search/smart	通过 query 字符串触发 CLIP 语义搜索	搜索频率过快会拉满 CPU，需在调用端做限流
专辑管理	POST /api/albums	动态创建专辑并建立资产关联	关联大量资产时，建议分批次调用，避免 API 超时
元数据更新	PUT /api/assets/{id}	修改照片的拍摄日期、地理位置等	修改地理位置后需触发后台重新索引

---

填坑实战：如何编写一个“稳如老狗”的自动同步脚本？

如果你想写一个 Python 脚本来同步你本地磁盘的照片，你可能会直接循环调用上传接口。这是典型的“新手错误”。一个架构师级别的同步工具必须包含以下逻辑：

1. 预检机制 (Pre-flight Check)：在上传前，先调用 POST /api/assets/bulk-upload-check。把本地文件的哈希值发过去，如果服务器上已经有了，直接跳过。这能节省 90% 的网络带宽。
2. 分块上传与并发控制：不要开启无限并发。对于视频文件，建议使用流式上传，并将并发数控制在 3-5 个，防止撑爆 Immich 的微服务队列。
3. 异常重试逻辑：由于 Immich 的后端在处理 AI 识别时可能会有短暂的响应延迟，你的脚本必须具备指数退避（Exponential Backoff）的重试能力，而不是一报错就退出。

---

痛点排雷：为什么你的 API 响应是 401 或 413？

在实战中，开发者最常踩的两个坑：

• 401 Unauthorized：除了 Key 写错，最常见的是 Nginx 反向代理拦截了自定义的 x-api-key 请求头。记得在 Nginx 配置中开启 underscores_in_headers on;。
• 413 Payload Too Large：这通常不是 Immich 的限制，而是你的 Nginx 默认 client_max_body_size 太小（默认 1M）。将其改为 0（不限制）或 10G，才能顺利上传大视频。

---

降维打击：获取 GitCode 《Immich 自动化同步 Python 脚本模板》

与其从零开始啃 Swagger 文档，不如直接站在巨人的肩膀上。

我已经针对“服务器本地照片自动同步”和“基于搜索结果的自动归档”这两个高频需求，在 GitCode 维护了一个**《Immich 开发者工具箱》**。里面包含了完整的 Python SDK 封装、带有进度条的多线程上传脚本，以及如何利用 GitHub Actions 实现自动同步的 CI/CD 配置。

直接前往 GitCode 访问这些脚本。别再把 Immich 当成一个死板的相册，用代码激活它的全部潜力，构建属于你的智能影像中枢。

[获取 GitCode 《Immich 开发者工具箱：自动同步与 API 调优脚本》]