文件管理

用户上传的文件（图片、视频、文档等）以及 AI 生成的文件统一管理。

端点列表

方法	路径	说明
GET	/api/v1/files	文件列表（支持按类型、标签过滤）
POST	/api/v1/files	上传文件
GET	/api/v1/files/{id}	文件详情
DELETE	/api/v1/files/{id}	删除文件

文件响应示例

{
  "id": "e5f6a7b8-...",
  "created_at": "2026-03-24T10:00:00Z",
  "file_name": "design-draft.png",
  "file_type": "image",
  "mime_type": "image/png",
  "file_size": 2048576,
  "status": "completed",
  "download_url": "https://cdn.example.com/files/design-draft.png",
  "error_message": null,
  "source": "upload",
  "created_by_id": "550e8400-..."
}

文件状态

状态	说明
pending	等待处理（如 AI 生成中）
processing	处理中
completed	已完成，可下载
failed	处理失败

文件来源

来源	说明
upload	用户手动上传
generation	AI 生成
duplicate	秒传（内容去重）

文件类型

类型	说明
image	图片
video	视频
audio	音频
document	文档

列表查询参数

除标准分页参数外，支持：

参数	类型	说明
file_type	string	按文件类型过滤
source	string	按来源过滤
status	string	按状态过滤

文件上传

通过 multipart/form-data 上传文件，具体格式参见 API Schema。

存储配额

• 每个用户有存储配额限制
• 超限时上传返回 413 Payload Too Large
• 内容相同的文件自动去重（秒传），不额外占用配额

测试要点

测试建议

1. 文件大小限制：超过单文件大小限制应返回 413
2. 存储配额：总存储超限时应返回 413
3. 秒传去重：上传内容相同的文件应触发秒传，不重复存储
4. 并发秒传：两个用户同时上传相同文件的并发安全性
5. 下载链接：completed 状态的文件应有有效的 download_url
6. 删除清理：删除文件后 download_url 应失效
7. 权限隔离：用户不能访问/删除他人的文件