Immich API 密钥与命令行上传：批量导入的自动化路径
网页拖拽和手机备份之外，Immich 还有第三条上传通道：命令行。几百 GB 的历史照片、按目录归档的素材库、想写脚本定时同步的备份流——都走这条路。底层是同一套公开 API，写程序对接也靠它。
第一步：生成 API 密钥
网页端 用户设置 → API Keys 创建。v1.135.0 起支持细粒度权限：可以造一把「只能上传」的钥匙给脚本用，把删除、用户管理等权限留在交互账号手里——这是把自动化放进生产环境前该做的基本卫生。
密钥即凭证，泄露等于交出账号对应权限；用不着的旧钥匙及时吊销。
第二步：装 CLI
Immich 官方 CLI 有两种装法：
npm 安装（需要 Node.js 22+）：
npm i -g @immich/cliDocker 运行（不装 Node 的替代）：
docker run -it -v "$(pwd)":/import:ro \
-e IMMICH_INSTANCE_URL=https://你的域名/api \
-e IMMICH_API_KEY=你的密钥 \
ghcr.io/immich-app/immich-cli:latest老版本的 immich（legacy CLI）需要先卸载再装新的 @immich/cli，两个不是同一个包。
第三步：登录
immich login http://服务器IP:2283/api 你的API密钥凭证会存在 ~/.config/immich/auth.yml——公用的机器上用完记得 immich logout。
第四步：上传的常用姿势
immich upload --recursive --album 照片目录/这可能是最常用的一条：递归上传目录，并按子目录名自动创建同名相册——「目录结构变相册结构」一步到位，和 外部库「原地不动」是两种口味，按需选。
值得认识的参数（完整清单 immich upload --help）：
| 参数 | 作用 |
|---|---|
--dry-run | 试运行：只显示会做什么，不动真格 |
--album-name "名字" | 全部传进指定相册 |
--ignore 模式 | 按通配符跳过文件（如 **/Raw/**） |
--include-hidden | 连隐藏文件一起传 |
--visibility archive/locked | 上传后直接归档/锁定，不进时间线 |
--delete-duplicates | 删除本地已存在服务器上的重复文件 |
--watch | 持续监视目录，有新文件自动传 |
--concurrency N | 并发上传数（默认 4） |
去重方面可以放心：CLI 传前默认先算哈希（--skip-hash 可跳过求快），服务器端本身也做内容去重——双保险，重复文件不会存两份。
对接 API 的开发者视角
CLI 背后是 Immich 的 REST API：官方 API 文档站列全了端点，v3.2.0 上线的 Search API v2 支持相册内搜索与 AND/OR 条件组合。自建工具的常见路线：定时任务扫目录 → API 上传 → 按规则打标签/建相册。写之前记得给密钥配最小权限。
从谷歌相册搬家是特例
如果你的历史照片在谷歌相册，别用 CLI 硬传——Takeout 导出的分卷压缩包需要专门工具处理，见 从谷歌相册搬家。