相册鉴权接口文档
概览
- 基础路径: /api
- 文档范围: 鉴权路由中的 album 模块接口
- 鉴权方式: 请求头 X-Token
鉴权头
| 字段 |
类型 |
必填 |
说明 |
| X-Token |
string |
是 |
用户登录后获得的 JWT Token |
媒体对象字段说明
| 字段 |
类型 |
说明 |
| userId |
integer |
所属用户 ID |
| deviceId |
string |
设备 ID |
| type |
string |
媒体类型，photo 或 video |
| title |
string |
标题，上传时通常为原文件名 |
| url |
string |
媒体访问地址。列表与上传返回的是已签名访问链接 |
| thumbnail |
string |
缩略图访问地址。返回时通常也是签名链接 |
| duration |
integer |
视频时长，秒 |
| createdAt |
string |
创建时间 |
1. 获取相册列表
- 路径: /api/album/list
- 方法: POST
- 是否鉴权: 是
- Content-Type: application/json
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| deviceId |
string |
否 |
设备 ID |
| type |
string |
否 |
媒体类型筛选，通常为 photo 或 video |
| page |
integer |
否 |
页码，默认 1 |
| pageSize |
integer |
否 |
每页条数，默认 20 |
请求示例
{
"deviceId": "dev_001",
"type": "photo",
"page": 1,
"pageSize": 20
}
成功响应示例
{
"code": 200,
"msg": "操作成功",
"data": {
"list": [
{
"userId": 1,
"deviceId": "dev_001",
"type": "photo",
"title": "cat.jpg",
"url": "https://example.com/uploads/...?...",
"thumbnail": "https://example.com/uploads/...?...",
"duration": 0,
"createdAt": "2026-05-09T10:00:00Z"
}
],
"total": 1
}
}
失败响应示例
{
"code": 400,
"msg": "参数错误",
"data": null
}
{
"code": 500,
"msg": "获取相册列表失败",
"data": null
}
2. 上传图片或视频
- 路径: /api/album/upload
- 方法: POST
- 是否鉴权: 是
- Content-Type: multipart/form-data
Form-Data 参数
| 字段 |
类型 |
必填 |
说明 |
| deviceId |
string |
否 |
关联设备 ID |
| file |
file |
是 |
上传的图片或视频文件 |
支持文件类型
- 图片: .jpg、.jpeg、.png、.gif、.webp
- 视频/音频: .mp4、.wav、.avi、.ts
业务说明
- 文件大小不能超过配置中的上传上限。
- 成功后返回签名后的 url 和 thumbnail。
- 超出配额时，服务端会异步清理最早的多余文件。
成功响应示例
{
"code": 200,
"msg": "上传成功",
"data": {
"userId": 1,
"deviceId": "dev_001",
"type": "photo",
"title": "cat.jpg",
"url": "https://example.com/uploads/...?...",
"thumbnail": "https://example.com/uploads/...?...",
"duration": 0,
"createdAt": "2026-05-09T10:00:00Z"
}
}
失败响应示例
{
"code": 400,
"msg": "请上传文件",
"data": null
}
{
"code": 400,
"msg": "不支持的文件类型",
"data": null
}
3. 删除媒体文件
- 路径: /api/album/delete
- 方法: POST
- 是否鉴权: 是
- Content-Type: application/json
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| deviceId |
string |
是 |
设备 ID |
| url |
string |
是 |
媒体文件标识。这里应传数据库中保存的文件名，不是签名后的完整访问链接 |
请求示例
{
"deviceId": "dev_001",
"url": "20260509100000_photo.jpg"
}
成功响应示例
{
"code": 200,
"msg": "删除成功",
"data": null
}
失败响应示例
{
"code": 400,
"msg": "参数错误",
"data": null
}
{
"code": 400,
"msg": "删除失败",
"data": null
}
附录
说明
- 当前鉴权路由里未注册抓拍接口 Capture，因此本文档仅覆盖 list、upload、delete。
- 列表和上传返回的 URL 已经带签名，适合直接访问。