KiteKite

相册

相册的创建、更新、列表与删除。

相册是文件的逻辑分组。每个用户可以拥有多个相册，文件通过 album_id 归属到某个相册。

说明

相册是可选的 —— 上传时不指定 album_id 的文件不归属任何相册。

相册对象结构

TYPESCRIPT
interface Album {
  id:          string
  user_id:     string
  name:        string
  description: string
  is_public:   boolean           // 公开相册可被匿名访问
  cover_url:   string | null
  file_count:  number            // 动态计算，非数据库列
  created_at:  string
  updated_at:  string
}

创建相册

Endpoint

POST · /api/v1/albums · 需认证

请求

JSON
{
  "name": "旅行照片",
  "description": "2026 春季东京",
  "is_public": false
}
字段约束
name必填，最长 100 字符
description可选，最长 500 字符
is_public默认 false

响应

JSON
{
  "code": 0,
  "data": {
    "id": "album-uuid",
    "user_id": "user-uuid",
    "name": "旅行照片",
    "description": "2026 春季东京",
    "is_public": false,
    "created_at": "2026-04-17T10:00:00Z",
    "updated_at": "2026-04-17T10:00:00Z"
  }
}

相册列表

Endpoint

GET · /api/v1/albums · 需认证

返回当前用户的全部相册，每条附带 file_count。

查询参数

参数默认说明
page1页码
size20每页数量（最大 100）

响应

JSON
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "album-uuid",
        "name": "旅行照片",
        "description": "2026 春季东京",
        "is_public": false,
        "file_count": 24,
        "created_at": "2026-04-17T10:00:00Z",
        "updated_at": "2026-04-17T10:00:00Z"
      }
    ],
    "total": 5,
    "page": 1,
    "size": 20
  }
}

更新相册

Endpoint

PUT · /api/v1/albums/:id · 需认证

所有字段可选，仅更新传入的字段。

请求

JSON
{
  "name": "2026 春·东京",
  "is_public": true
}

错误

Code条件
40300非相册所有者
40400相册不存在

删除相册

Endpoint

DELETE · /api/v1/albums/:id · 需认证

删除相册不会删除其中的文件 —— 相关文件的 album_id 被置为 null，文件本身仍然存在。

向相册添加文件

相册 ID 在上传时传入即可：

HTTP
POST /api/v1/upload
Authorization: Bearer YOUR_TOKEN
Content-Type: multipart/form-data

file=<file>
album_id=album-uuid

现有文件若需要改变归属，目前建议通过后台操作；后续版本会暴露专用的「移动到相册」接口。

下一步