aitori-web-v2/doc/AI_ALBUM_API.md

相册管理 API 文档

本文档描述相册管理查询接口规范。

1. 全局响应结构

所有接口返回值均由统一响应结构包装，格式如下：

{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {},
  "timestamp": 1709628736123
}

---

2. 相册列表查询

• URL: /v2/ai/album/list
• Method: GET
• 描述: 分页查询相册列表，关联用户信息（昵称、邮箱、苹果用户ID、平台、语言）。

请求参数

字段名	类型	必填	说明
page	integer	否	页码，默认 1
size	integer	否	每页大小，默认 10
id	long	否	相册ID（精确匹配）
userId	long	否	用户ID
title	string	否	标题（模糊匹配）
taskId	string	否	任务ID（精确匹配）
orderId	string	否	订单ID（精确匹配）
status	integer	否	写真状态（1:处理中 2:生成中 3:已完成）
startTime	string	否	开始时间（yyyy-MM-dd HH:mm:ss）
endTime	string	否	结束时间（yyyy-MM-dd HH:mm:ss）

响应参数（data 字段）

返回 Mybatis-Plus 分页对象，包含 records、total、size、current、pages 等字段。

records 中每条数据（AiAlbumVO）结构如下：

字段名	类型	说明
id	long	相册ID
title	string	标题
userId	long	用户ID
styleId	integer	风格ID
taskId	string	任务ID
status	integer	写真状态（1:处理中 2:生成中 3:已完成）
pictures	string	写真照片
videos	string	视频
accelerate	integer	是否加速（0:否 1:是）
timestamp	long	预计花费时间（秒）
createTime	string	创建时间
updateTime	string	最后更新时间
orderId	string	订单ID
type	integer	类型（1:分身相册 2:普通相册）
expectTime	string	预计完成时间
videoImage	string	视频的原始图片
nickname	string	用户昵称
email	string	用户邮箱
appleUserId	string	苹果用户ID
platform	string	平台
language	string	语言

示例请求

GET /v2/ai/album/list?page=1&size=10&userId=10001&status=3

示例响应

{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {
    "records": [
      {
        "id": 90001,
        "title": "春日写真集",
        "userId": 10001,
        "styleId": 301,
        "taskId": "TASK_998877",
        "status": 3,
        "pictures": "[\"https://cdn.example.com/p1.jpg\"]",
        "videos": "[\"https://cdn.example.com/v1.mp4\"]",
        "accelerate": 1,
        "timestamp": 300,
        "createTime": "2026-03-10 09:30:00",
        "updateTime": "2026-03-10 09:36:20",
        "orderId": "ORD_202603100001",
        "type": 2,
        "expectTime": "2026-03-10 09:40:00",
        "videoImage": "[\"https://cdn.example.com/raw1.jpg\"]",
        "nickname": "Tom",
        "email": "tom@example.com",
        "appleUserId": "apple_user_001",
        "platform": "ios",
        "language": "zh-CN"
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  },
  "timestamp": 1773033000000
}

---

3. 相册详情查询

• URL: /v2/ai/album/get/{id}
• Method: GET
• 描述: 根据相册ID获取相册详情（返回结构同 AiAlbumVO）。

请求参数

字段名	类型	必填	说明
id	long	是	相册ID

响应参数（data 字段）

返回 AiAlbumVO，字段定义同上。

示例请求

GET /v2/ai/album/get/90001

示例响应

{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {
    "id": 90001,
    "title": "春日写真集",
    "userId": 10001,
    "styleId": 301,
    "taskId": "TASK_998877",
    "status": 3,
    "pictures": "[\"https://cdn.example.com/p1.jpg\"]",
    "videos": "[\"https://cdn.example.com/v1.mp4\"]",
    "accelerate": 1,
    "timestamp": 300,
    "createTime": "2026-03-10 09:30:00",
    "updateTime": "2026-03-10 09:36:20",
    "orderId": "ORD_202603100001",
    "type": 2,
    "expectTime": "2026-03-10 09:40:00",
    "videoImage": "[\"https://cdn.example.com/raw1.jpg\"]",
    "nickname": "Tom",
    "email": "tom@example.com",
    "appleUserId": "apple_user_001",
    "platform": "ios",
    "language": "zh-CN"
  },
  "timestamp": 1773033000000
}