本文档提供了 Immich REST API 的技术信息。它涵盖了 API 结构、身份验证方法和可用端点。有关具体的实现细节和工作流程，您可以参考开发指南。
Immich 提供了一个全面的 RESTful API，支持其所有客户端应用程序（网页、移动端、命令行界面），并可用于自定义集成。该 API 使用 NestJS 构建，并在/api基本路径下提供服务。
来源：server/package.json, open-api/immich-openapi-specs.json, open-api/typescript-sdk/src/fetch-client.ts
Immich 的 API 支持三种身份验证方法
| 方法 | 描述 | 用途 |
|---|---|---|
| JWT 持有者令牌 | 使用 JWT 令牌进行身份验证 | Authorization: Bearer <token> 头 |
| API密钥 | 使用客户端生成的 API 密钥进行身份验证 | x-api-key: <api-key> 头 |
| Cookie | 使用 Cookie 进行基于会话的身份验证 | 登录后自动设置 |
所有受保护的端点都需要其中一种身份验证方法。公共端点（例如共享链接）可能不需要身份验证。
来源：open-api/immich-openapi-specs.json, open-api/typescript-sdk/src/fetch-client.ts
Immich API 按照与应用程序功能一致的逻辑域进行组织。以下是主要 API 域的概述
来源：open-api/immich-openapi-specs.json
以下是主要的端点类别。每个类别都包含多个操作（GET、POST、PUT、DELETE），用于管理相应的资源。
处理系统中与照片和视频相关的所有操作。
| 端点 | 描述 |
|---|---|
GET /assets/{id} | 获取资产信息 |
POST /assets | 上传新资产 |
GET /assets/{id}/thumbnail | 获取资产缩略图 |
GET /assets/{id}/original | 下载原始资产 |
PUT /assets/{id} | 更新资产元数据 |
DELETE /assets | 删除资产 |
GET /assets/statistics | 获取资产统计数据 |
GET /assets/random | 获取随机资产 |
来源：open-api/immich-openapi-specs.json, mobile/openapi/README.md
管理相册和共享收藏。
| 端点 | 描述 |
|---|---|
GET /albums | 获取所有相册 |
POST /albums | 创建新相册 |
GET /albums/{id} | 获取相册信息 |
PATCH /albums/{id} | 更新相册信息 |
DELETE /albums/{id} | 删除相册 |
PUT /albums/{id}/assets | 将资产添加到相册 |
DELETE /albums/{id}/assets | 从相册中移除资产 |
PUT /albums/{id}/users | 将用户添加到相册 |
来源：open-api/immich-openapi-specs.json, mobile/openapi/README.md
管理用户身份验证和访问控制。
| 端点 | 描述 |
|---|---|
POST /auth/login | 用户登录 |
POST /auth/logout | 用户注销 |
POST /auth/change-password | 更改用户密码 |
POST /auth/validateToken | 验证访问令牌 |
POST /auth/admin-sign-up | 管理员注册 |
来源：open-api/immich-openapi-specs.json, mobile/openapi/README.md
处理用户管理和偏好设置。
| 端点 | 描述 |
|---|---|
GET /users/me | 获取当前用户信息 |
PUT /users/me | 更新当前用户 |
GET /users | 获取所有用户 |
GET /users/{id} | 获取特定用户 |
PUT /users/me/profile-image | 更新个人资料图片 |
GET /users/me/preferences | 获取用户偏好设置 |
PUT /users/me/preferences | 更新用户偏好设置 |
来源：open-api/immich-openapi-specs.json
管理用于媒体导入的外部库。
| 端点 | 描述 |
|---|---|
GET /libraries | 获取所有库 |
POST /libraries | 创建新库 |
GET /libraries/{id} | 获取库信息 |
PUT /libraries/{id} | 更新库 |
DELETE /libraries/{id} | 删除库 |
POST /libraries/{id}/scan | 扫描库以查找新资产 |
POST /libraries/{id}/validate | 验证库配置 |
来源：open-api/immich-openapi-specs.json
API 使用 JSON 对象作为请求和响应体。以下是一些核心数据模型
{
"id": "string (UUID)",
"deviceAssetId": "string",
"ownerId": "string (UUID)",
"libraryId": "string (UUID)",
"deviceId": "string",
"type": "IMAGE | VIDEO",
"originalPath": "string",
"originalFileName": "string",
"fileCreatedAt": "string (ISO date)",
"fileModifiedAt": "string (ISO date)",
"thumbhash": "string",
"exifInfo": { ... },
"smartInfo": { ... },
"livePhotoVideoId": "string (UUID)",
"tags": [ ... ],
"stack": { ... }
}
来源：open-api/typescript-sdk/src/fetch-client.ts
{
"id": "string (UUID)",
"ownerId": "string (UUID)",
"albumName": "string",
"description": "string",
"createdAt": "string (ISO date)",
"updatedAt": "string (ISO date)",
"albumThumbnailAssetId": "string (UUID)",
"shared": boolean,
"hasSharedLink": boolean,
"assets": [ ... ],
"owner": { ... },
"sharedUsers": [ ... ]
}
来源：open-api/typescript-sdk/src/fetch-client.ts
Immich 提供官方 SDK 以便更轻松地集成
来源：open-api/typescript-sdk/package.json, cli/package.json
来源：mobile/openapi/lib/api.dart, mobile/openapi/lib/api_client.dart
API 错误遵循标准结构
常见 HTTP 状态码
| 状态码 | 描述 |
|---|---|
| 400 | 不良请求 - 参数无效或请求格式错误 |
| 401 | 未授权 - 需要身份验证 |
| 403 | 禁止访问 - 无权访问资源 |
| 404 | 未找到 - 资源不存在 |
| 500 | 服务器错误 - 服务器发生意外错误 |
来源：open-api/immich-openapi-specs.json
API 版本与 Immich 服务器版本绑定，当前为1.131.3。API 版本之间可能会有变化，但 Immich 尽量保持向后兼容性。
来源：server/package.json, open-api/typescript-sdk/package.json, mobile/openapi/README.md
完整的 API 文档使用 OpenAPI/Swagger 生成，在运行 Immich 服务器时可通过/api/docs访问。这提供了一个交互式界面，用于探索和测试所有可用端点。
来源：open-api/immich-openapi-specs.json, server/package.json, open-api/typescript-sdk/src/fetch-client.ts