ai/docs/system_b/06_API接口设计文档.md

# 06_API接口设计文档

## 1. 文档目标

本文档定义系统 B 的 API 接口结构、请求参数、返回格式、错误码和权限要求。

## 2. 通用规范

### 2.1 Base URL

```text
/api
```

后台接口：

```text
/api/admin
```

### 2.2 通用返回格式

```json
{
  "code": 0,
  "message": "ok",
  "data": {}
}
```

错误示例：

```json
{
  "code": 40001,
  "message": "照片质量不合格",
  "data": {
    "reason": "face_blur"
  }
}
```

### 2.3 通用错误码

| code | 含义 |
|---|---|
| 0 | 成功 |
| 40000 | 参数错误 |
| 40100 | 未登录 |
| 40300 | 无权限 |
| 40400 | 资源不存在 |
| 40900 | 状态冲突 |
| 42900 | 请求过于频繁 |
| 50000 | 系统错误 |
| 60000 | AI 生成失败 |
| 60001 | Provider 不可用 |
| 70000 | 支付失败 |
| 80000 | 审核不通过 |

## 3. 认证接口

### 3.1 发送验证码

```text
POST /api/auth/send-code
```

请求：

```json
{ "phone": "13800000000" }
```

返回：

```json
{ "success": true }
```

### 3.2 手机号登录

```text
POST /api/auth/login-phone
```

请求：

```json
{
  "phone": "13800000000",
  "code": "123456"
}
```

返回：

```json
{
  "token": "jwt-token",
  "user": { "id": 1, "nickname": "用户" }
}
```

### 3.3 微信登录

```text
POST /api/auth/login-wechat
```

请求：

```json
{ "code": "wechat_code" }
```

## 4. 首页与案例接口

### 4.1 首页配置

```text
GET /api/home
```

返回：

```json
{
  "banners": [],
  "featured_cases": [],
  "themes": [],
  "packages": []
}
```

### 4.2 案例列表

```text
GET /api/cases?theme_id=1&style_id=2&page=1&page_size=20
```

### 4.3 案例详情

```text
GET /api/cases/:id
```

## 5. 模板查询接口

### 5.1 人生主题列表

```text
GET /api/life-themes
```

### 5.2 套餐列表

```text
GET /api/packages?theme_id=1
```

### 5.3 风格列表

```text
GET /api/styles?theme_id=1
```

### 5.4 世界观列表

```text
GET /api/worlds?theme_id=1&style_id=2
```

### 5.5 场景列表

```text
GET /api/worlds/:world_id/scenes
```

## 6. 项目接口

### 6.1 创建项目

```text
POST /api/projects
```

请求：

```json
{
  "title": "我们的时空纪念片",
  "life_theme_id": 1,
  "output_type": "video"
}
```

返回：

```json
{
  "project_id": 1001,
  "status": "draft"
}
```

### 6.2 获取项目详情

```text
GET /api/projects/:id
```

### 6.3 保存套餐

```text
POST /api/projects/:id/package
```

请求：

```json
{ "package_id": 2 }
```

### 6.4 保存风格

```text
POST /api/projects/:id/style
```

请求：

```json
{ "style_id": 3 }
```

### 6.5 保存世界观

```text
POST /api/projects/:id/worlds
```

请求：

```json
{
  "selected_worlds": [
    { "world_id": 1, "sort_order": 1 },
    { "world_id": 5, "sort_order": 2 }
  ]
}
```

### 6.6 保存场景

```text
POST /api/projects/:id/scenes
```

请求：

```json
{
  "selected_scenes": [
    { "world_id": 1, "scene_id": 11, "sort_order": 1 },
    { "world_id": 5, "scene_id": 51, "sort_order": 2 }
  ]
}
```

### 6.7 保存定制信息

```text
POST /api/projects/:id/custom-info
```

请求：

```json
{
  "names": { "person_a": "男方", "person_b": "女方" },
  "relationship_type": "couple",
  "anniversary_date": "2026-05-20",
  "copy_mood": "romantic",
  "show_names": true,
  "show_date": true,
  "vow_text": "愿此生与你共赴山海",
  "special_requirements": "整体梦幻，不要太搞笑",
  "allow_public_case": false
}
```

### 6.8 项目进度

```text
GET /api/projects/:id/progress
```

返回：

```json
{
  "status": "final_generating",
  "percent": 65,
  "current_step": "正式图片生成中",
  "tasks": [
    { "task_type": "final_image", "success": 12, "total": 20 }
  ]
}
```

### 6.9 我的项目列表

```text
GET /api/my/projects?page=1&page_size=20
```

## 7. 文件与照片接口

### 7.1 上传照片

```text
POST /api/projects/:id/photos
Content-Type: multipart/form-data
```

字段：

```text
person_role: person_a/person_b/child/self
file: image
```

返回：

```json
{
  "asset_id": 2001,
  "url": "signed-url",
  "status": "uploaded"
}
```

### 7.2 删除照片

```text
DELETE /api/assets/:asset_id
```

### 7.3 触发照片质检

```text
POST /api/projects/:id/photo-check
```

### 7.4 获取照片质检结果

```text
GET /api/projects/:id/photo-check-result
```

## 8. 授权接口

### 8.1 提交授权确认

```text
POST /api/projects/:id/authorizations
```

请求：

```json
{
  "types": ["photo_usage", "privacy_policy", "terms"],
  "minor_guardian_confirmed": false
}
```

### 8.2 公开案例授权

```text
POST /api/projects/:id/public-case-authorization
```

## 9. AI 生成流程接口

### 9.1 生成创作方案

```text
POST /api/projects/:id/generate-plan
```

返回：

```json
{
  "task_id": 3001,
  "status": "pending"
}
```

### 9.2 获取创作方案

```text
GET /api/projects/:id/plan
```

### 9.3 确认创作方案

```text
POST /api/projects/:id/confirm-plan
```

### 9.4 生成预览

```text
POST /api/projects/:id/generate-preview
```

### 9.5 确认预览

```text
POST /api/projects/:id/confirm-preview
```

### 9.6 正式生成

```text
POST /api/projects/:id/generate-final
```

### 9.7 获取项目素材

```text
GET /api/projects/:id/assets?asset_type=final_image
```

## 10. 订单支付接口

### 10.1 创建订单

```text
POST /api/projects/:id/orders
```

请求：

```json
{ "package_id": 2, "pay_method": "wechat" }
```

### 10.2 获取支付状态

```text
GET /api/orders/:id
```

### 10.3 支付回调

```text
POST /api/payments/wechat/callback
```

## 11. 修改申请接口

### 11.1 提交修改申请

```text
POST /api/projects/:id/revisions
```

请求：

```json
{
  "revision_type": "small",
  "request_text": "请把片尾日期改成 2026-05-20"
}
```

### 11.2 修改申请列表

```text
GET /api/projects/:id/revisions
```

## 12. 下载接口

### 12.1 获取下载链接

```text
GET /api/assets/:asset_id/download-url
```

返回：

```json
{
  "url": "signed-download-url",
  "expires_in": 3600
}
```

## 13. 后台接口示例

### 13.1 后台项目列表

```text
GET /api/admin/projects?status=manual_review&page=1&page_size=20
```

### 13.2 后台项目详情

```text
GET /api/admin/projects/:id
```

### 13.3 后台任务重试

```text
POST /api/admin/tasks/:id/retry
```

### 13.4 后台任务终止

```text
POST /api/admin/tasks/:id/cancel
```

### 13.5 后台转人工

```text
POST /api/admin/projects/:id/manual-review
```

### 13.6 后台模板新增/编辑

```text
POST /api/admin/world-templates
PUT /api/admin/world-templates/:id
POST /api/admin/scene-templates
PUT /api/admin/scene-templates/:id
```

### 13.7 后台 Provider 测试

```text
POST /api/admin/providers/:id/test
```

## 14. WebSocket 进度推送

连接：

```text
/ws/projects/:project_id
```

事件：

```json
{
  "event": "project_progress",
  "data": {
    "project_id": 1001,
    "status": "video_rendering",
    "percent": 82,
    "message": "视频合成中"
  }
}
```

## 15. 权限规则

- 用户只能访问自己的项目、素材、订单。
- 后台管理员按角色权限访问后台接口。
- Provider 密钥不可通过接口返回明文。
- 公开案例必须检查授权记录。

## 16. V3 真人动态视频接口增量

### 16.1 输出模式

```text
PATCH /api/projects/:id/output-mode
```

请求：

```json
{
  "output_mode": "real_video"
}
```

### 16.2 身份锚点

```text
POST /api/projects/:id/identity-anchors/generate
GET  /api/projects/:id/identity-anchors
POST /api/identity-anchors/:anchor_id/confirm
POST /api/identity-anchors/:anchor_id/reject
```

### 16.3 人脸一致性质检

```text
POST /api/person-profiles/:person_id/face-consistency/check
GET  /api/person-profiles/:person_id/face-consistency/latest
```

### 16.4 动作模板

```text
GET /api/motion-templates
GET /api/admin/motion-templates
POST /api/admin/motion-templates
PUT /api/admin/motion-templates/:id
```

### 16.5 真人动态视频片段

```text
GET  /api/projects/:id/video-clips
GET  /api/projects/:id/video-clips/cost-estimate
POST /api/projects/:id/video-clips/generate
POST /api/video-clips/:clip_id/retry
POST /api/video-clips/:clip_id/quality-check
POST /api/video-clips/:clip_id/replace
```

真实生成请求必须包含：

```json
{
  "provider_code": "minimax_hailuo_23_fast",
  "confirm_real_video": true,
  "max_cost_per_clip": 1.0
}
```

未确认或 Provider 未启用时，应返回明确错误，不允许回落 mock。

### 16.6 口型任务

```text
POST /api/video-clips/:clip_id/lipsync
GET  /api/projects/:id/lipsync-tasks
POST /api/lipsync-tasks/:task_id/retry
```