immich-automated-selfie-timelapse 与 Immich API 集成原理:按人物搜索照片并解析人脸元数据全流程

原创2026-10-31 23:57:082,175 阅读

immich-automated-selfie-timelapse 与 Immich API 集成原理:按人物搜索照片并解析人脸元数据全流程

immich-automated-selfie-timelapse 是一个基于 Immich API 构建的自动化人脸处理工具:它调用 Immich 的人脸识别数据,按人物搜索照片库,解析每张照片的人脸边界框元数据,再经过裁剪、对齐、滤镜等多级流水线处理,最终把某个人物多年的照片自动编译成一段平滑的自拍延时视频(selfie timelapse)。本文将带你完整拆解"从人物检索到人脸元数据解析"的集成全流程。

selfie timelapse 延时视频最终效果

一、整体架构:一个客户端串起整条链路

整个集成核心集中在 src/immich_api/mod.rs 中的 ImmichClient。它封装了与 Immich 服务端通信的全部 HTTP 请求,对外提供 5 类能力:

方法 对应 Immich 端点 作用
validate_connection GET /server/about 校验 API Key 与连通性
get_people GET /people 获取所有人像列表(人物 ID + 名称)
get_person_thumbnail GET /people/{id}/thumbnail 获取人物头像缩略图
get_assets_with_person POST /search/metadata 按人物 ID 分页搜索照片
download_asset / download_asset_preview GET /assets/{id}/original 或 thumbnail?size=preview 下载原图或 1440p 预览图

所有请求都携带 x-api-key 请求头。客户端在初始化时会对 base URL 做规范化(sanitize_base_url):无论你填 http://host:2283 还是 http://host:2283/api/,最终都会统一成 .../api 结尾,避免新手配置路径踩坑。

API Key 与地址通过环境变量 IMMICH_API_KEY、IMMICH_BASE_URL 注入(见 src/config.rs),需要开启的权限有:album.read、asset.download、asset.read、asset.view、person.read、server.about。

Immich 人脸处理流水线界面细节

二、第一步:连通性校验与错误处理

启动或点击"检查连接"时,ImmichClient 会请求 /server/about 获取 ServerInfo(版本号)。这一步由 Web 层 src/web/handlers/health.rs 的 check_connection 处理器调用,结果直接展示在 Web UI 的连接状态栏。

值得注意的工程设计是 check_response_error:它在判断 HTTP 状态码时区分了三种情况,给出面向用户的明确报错——

  • 401 → "invalid or expired API key"
  • 403 → "missing permission"(权限未勾选)
  • 其他 → 附带响应体的通用 HTTP 错误

这让新手在权限配错时能一眼定位问题,而不是面对一个笼统的"请求失败"。

三、第二步:按人物搜索照片

3.1 拉取人物列表

前端人物选择器(frontend/src/lib/components/PeopleSelector.svelte)背后的数据来自 GET /people。返回结果被反序列化为 Person 结构(id + 可选 name),头像则单独从 /people/{id}/thumbnail 获取。选中某个人后,界面还会调用 /api/people/{id}/asset-count(见 src/web/handlers/people.rs)预先统计该人物的照片总数与含人脸数据的照片数。

3.2 按人物 ID 分页搜索

核心搜索逻辑在 search_person_assets(src/immich_api/mod.rs)中。它向 POST /search/metadata 发送 SearchParams 请求体:

参数 值 说明
personIds 选中人物的 ID 按人物过滤
albumIds 可选 限定相册范围
takenAfter / takenBefore 可选 限定拍摄时间区间
type IMAGE 只搜索照片,排除视频
page / size 从 1 开始 / 每页 100 分页参数
withPeople true 关键:要求返回结果附带人物与人脸数据

withPeople: true 是整个集成的枢纽——只有带上它,Immich 才会把每张资产的人物归属及人脸信息一并返回。搜索循环持续翻页直到 next_page 为空(设有 1000 页保护上限)。

当选择了多个相册时,get_assets_with_person 会逐相册分别请求,再用 HashSet 按资产 ID 去重合并,避免同一张照片被重复处理。

四、第三步:解析人脸元数据

4.1 三层嵌套的数据结构

搜索返回的 JSON 按三层结构组织(见 src/immich_api/mod.rs):

Asset(照片资产)
└── people: Vec<PersonWithFaces>   // 照片中出现的所有人物
    └── faces: Vec<FaceData>       // 该人物在照片中的脸

其中 FaceData 就是人脸元数据本体:

字段 含义
bounding_box_x1 / y1 / x2 / y2 人脸边界框四个角点(像素坐标)
image_width / image_height 边界框所属图像的原始尺寸

4.2 为每个人物锁定"自己那张脸"

一张合影里可能有多个 PersonWithFaces。任务主流程在 src/job/mod.rs 的 find_face_for_person 中遍历资产内的人物列表,找出 id 等于目标人物 ID 的那一项,并取其第一张脸(Immich 不会对同一人在同一张照片中重复建脸)。没有人脸数据的资产会被直接过滤掉——因为后续所有裁剪、对齐都依赖这个边界框。

五、第四步:下载图像并进入处理流水线

5.1 两种下载策略

process_single_asset(src/job/processing.rs)根据配置 use_preview 决定:

  • 预览图模式(默认):下载 Immich 预生成的 1440p JPEG,解码快、体积小;
  • 原图模式:下载 /assets/{id}/original,下载前先检查 Content-Length,超过 100MB 直接拒绝,防止内存被超大文件撑爆。

5.2 人脸元数据在流水线中的用途

人脸边界框并非一次性的"下载定位器",它在流水线(src/pipeline/mod.rs)中至少被三处复用:

  1. face_resolution(src/pipeline/steps/face_resolution.rs):在下载之前先用 x2-x1、y2-y1 算出脸部像素尺寸,小于阈值(默认 80px)直接跳过——用最便宜的元数据先淘汰最没价值的照片,省下下载与计算开销;
  2. crop_and_resize(src/pipeline/crop_utils.rs):把元数据中的边界框按"实际下载尺寸 / 元数据尺寸"的比值缩放,才能精确裁出人脸区域。因为预览图与原图分辨率不同,这一步的坐标换算必不可少;
  3. 后续步骤:亮度、模糊、头部姿态、眨眼检测、基于 68 点面部特征的双眼对齐(src/pipeline/types.rs 中定义了 EAR 眨眼比、眼球旋转角等几何计算),最终统一输出 512×512 的定帧图像。

设置面板中的人脸处理参数配置

5.3 并行与配额控制

任务层用信号量控制并发(max_workers),每张图的跳过原因(如 face_too_small、blurry)都会汇入原子计数器实时推送到前端;若开启"每时间段限片",TimeIntervalTracker 会按天/周/月分桶限制入选照片数,避免某次旅行密集拍摄霸占整段视频。

六、成果产出与进度可视化

所有通过流水线的图片按 时间戳_资产ID.jpg 命名保存(保证时序),再由 FFmpeg 按配置的帧率与 CRF 编译为 MP4 延时视频(src/video/ffmpeg.rs)。

进度方面,Web 服务(src/web/handlers/mod.rs)暴露了完整的 REST 端点:/api/people、/api/start、/api/progress、/api/cancel 等,并通过 /api/ws 的 WebSocket 通道把每一步的完成数、跳过统计实时广播给前端,无需轮询。

总结

immich-automated-selfie-timelapse 与 Immich API 的集成可以归纳为一条清晰的链路:

API Key 校验 → /people 选人物 → /search/metadata(withPeople=true)按人物分页搜图 → 解析 FaceData 边界框 → 下载图像 → 流水线裁剪/对齐/过滤 → FFmpeg 合成视频

它充分利用了 Immich 已有的人脸识别能力,把"找照片"这件最难的事交给图库本身,自己专注做好"选片 + 对齐 + 合成",这正是其集成方案对新手最友好、也最值得借鉴的设计思路。

登录后查看全文
immich-automated-selfie-timelapse