aitori-bi-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
styleName	string	风格名称
styleCoverImg	string	风格封面图
standardPlanPoints	long	标准定价(积分)
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,
        "styleName": "春日写真",
        "styleCoverImg": "https://cdn.example.com/style-cover.jpg",
        "standardPlanPoints": 1990,
        "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,
    "styleName": "春日写真",
    "styleCoverImg": "https://cdn.example.com/style-cover.jpg",
    "standardPlanPoints": 1990,
    "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
}