Project: Pet Feeder | page_id: 1723
Album Authentication Interface Documentation
Overview
- Base path: /api
- Documentation scope: album module interfaces in the authenticated routes
- Authentication method: request header X-Token
Authentication Header
| Field |
Type |
Required |
Description |
| X-Token |
string |
Yes |
The JWT Token obtained after the user logs in |
Media Object Field Description
| Field |
Type |
Description |
| userId |
integer |
Owning user ID |
| deviceId |
string |
Device ID |
| type |
string |
Media type, photo or video |
| title |
string |
Title; usually the original file name when uploading |
| url |
string |
Media access address. The list and upload responses return a signed access link |
| thumbnail |
string |
Thumbnail access address. It is usually also a signed link when returned |
| duration |
integer |
Video duration in seconds |
| createdAt |
string |
Creation time |
1. Get the Album List
- Path: /api/album/list
- Method: POST
- Authentication required: Yes
- Content-Type: application/json
Request Body Parameters
| Field |
Type |
Required |
Description |
| deviceId |
string |
No |
Device ID |
| type |
string |
No |
Media type filter, usually photo or video |
| page |
integer |
No |
Page number, default 1 |
| pageSize |
integer |
No |
Number of items per page, default 20 |
Request Example
{
"deviceId": "dev_001",
"type": "photo",
"page": 1,
"pageSize": 20
}
Success Response Example
{
"code": 200,
"msg": "Operation successful",
"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
}
}
Failure Response Example
{
"code": 400,
"msg": "Parameter error",
"data": null
}
{
"code": 500,
"msg": "Failed to get the album list",
"data": null
}
2. Upload an Image or Video
- Path: /api/album/upload
- Method: POST
- Authentication required: Yes
- Content-Type: multipart/form-data
Form-Data Parameters
| Field |
Type |
Required |
Description |
| deviceId |
string |
No |
Associated device ID |
| file |
file |
Yes |
The image or video file to upload |
Supported File Types
- Images: .jpg、.jpeg、.png、.gif、.webp
- Video/audio: .mp4、.wav、.avi、.ts
Business Description
- The file size cannot exceed the upload limit in the configuration.
- After success, the signed url and thumbnail are returned.
- When the quota is exceeded, the server asynchronously cleans up the oldest excess files.
Success Response Example
{
"code": 200,
"msg": "Upload successful",
"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"
}
}
Failure Response Example
{
"code": 400,
"msg": "Please upload a file",
"data": null
}
{
"code": 400,
"msg": "Unsupported file type",
"data": null
}
3. Delete a Media File
- Path: /api/album/delete
- Method: POST
- Authentication required: Yes
- Content-Type: application/json
Request Body Parameters
| Field |
Type |
Required |
Description |
| deviceId |
string |
Yes |
Device ID |
| url |
string |
Yes |
Media file identifier. The file name saved in the database should be passed here, not the complete signed access link |
Request Example
{
"deviceId": "dev_001",
"url": "20260509100000_photo.jpg"
}
Success Response Example
{
"code": 200,
"msg": "Delete successful",
"data": null
}
Failure Response Example
{
"code": 400,
"msg": "Parameter error",
"data": null
}
{
"code": 400,
"msg": "Delete failed",
"data": null
}
Appendix
Description
- The capture interface Capture is not registered in the current authenticated routes, so this document only covers list, upload and delete.
- The URLs returned by the list and upload interfaces are already signed and suitable for direct access.