root/ai

Fork 0

Files

T

www 7a8191650f Initial AI manga platform

2026-06-15 17:45:28 +08:00

8.4 KiB

Executable File

Raw Blame History

06_API接口设计文档

1. 文档目标

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

2. 通用规范

2.1 Base URL

/api

后台接口：

/api/admin

2.2 通用返回格式

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

错误示例：

{
  "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 发送验证码

POST /api/auth/send-code

请求：

{ "phone": "13800000000" }

{ "success": true }

3.2 手机号登录

POST /api/auth/login-phone

请求：

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

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

3.3 微信登录

POST /api/auth/login-wechat

请求：

{ "code": "wechat_code" }

4. 首页与案例接口

4.1 首页配置

GET /api/home

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

4.2 案例列表

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

4.3 案例详情

GET /api/cases/:id

5. 模板查询接口

5.1 人生主题列表

GET /api/life-themes

5.2 套餐列表

GET /api/packages?theme_id=1

5.3 风格列表

GET /api/styles?theme_id=1

5.4 世界观列表

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

5.5 场景列表

GET /api/worlds/:world_id/scenes

6. 项目接口

6.1 创建项目

POST /api/projects

请求：

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

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

6.2 获取项目详情

GET /api/projects/:id

6.3 保存套餐

POST /api/projects/:id/package

请求：

{ "package_id": 2 }

6.4 保存风格

POST /api/projects/:id/style

请求：

{ "style_id": 3 }

6.5 保存世界观

POST /api/projects/:id/worlds

请求：

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

6.6 保存场景

POST /api/projects/:id/scenes

请求：

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

6.7 保存定制信息

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

请求：

{
  "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 项目进度

GET /api/projects/:id/progress

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

6.9 我的项目列表

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

7. 文件与照片接口

7.1 上传照片

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

字段：

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

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

7.2 删除照片

DELETE /api/assets/:asset_id

7.3 触发照片质检

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

7.4 获取照片质检结果

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

8. 授权接口

8.1 提交授权确认

POST /api/projects/:id/authorizations

请求：

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

8.2 公开案例授权

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

9. AI 生成流程接口

9.1 生成创作方案

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

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

9.2 获取创作方案

GET /api/projects/:id/plan

9.3 确认创作方案

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

9.4 生成预览

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

9.5 确认预览

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

9.6 正式生成

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

9.7 获取项目素材

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

10. 订单支付接口

10.1 创建订单

POST /api/projects/:id/orders

请求：

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

10.2 获取支付状态

GET /api/orders/:id

10.3 支付回调

POST /api/payments/wechat/callback

11. 修改申请接口

11.1 提交修改申请

POST /api/projects/:id/revisions

请求：

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

11.2 修改申请列表

GET /api/projects/:id/revisions

12. 下载接口

12.1 获取下载链接

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

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

13. 后台接口示例

13.1 后台项目列表

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

13.2 后台项目详情

GET /api/admin/projects/:id

13.3 后台任务重试

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

13.4 后台任务终止

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

13.5 后台转人工

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

13.6 后台模板新增/编辑

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 测试

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

14. WebSocket 进度推送

连接：

/ws/projects/:project_id

事件：

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

15. 权限规则

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

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

16.1 输出模式

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

请求：

{
  "output_mode": "real_video"
}

16.2 身份锚点

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 人脸一致性质检

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

16.4 动作模板

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

16.5 真人动态视频片段

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

真实生成请求必须包含：

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

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

16.6 口型任务

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

8.4 KiB Executable File Raw Blame History

06_API接口设计文档

1. 文档目标

2. 通用规范

2.1 Base URL

2.2 通用返回格式

2.3 通用错误码

3. 认证接口

3.1 发送验证码

3.2 手机号登录

3.3 微信登录

4. 首页与案例接口

4.1 首页配置

4.2 案例列表

4.3 案例详情

5. 模板查询接口

5.1 人生主题列表

5.2 套餐列表

5.3 风格列表

5.4 世界观列表

5.5 场景列表

6. 项目接口

6.1 创建项目

6.2 获取项目详情

6.3 保存套餐

6.4 保存风格

6.5 保存世界观

6.6 保存场景

6.7 保存定制信息

6.8 项目进度

6.9 我的项目列表

7. 文件与照片接口

7.1 上传照片

7.2 删除照片

7.3 触发照片质检

7.4 获取照片质检结果

8. 授权接口

8.1 提交授权确认

8.2 公开案例授权

9. AI 生成流程接口

9.1 生成创作方案

9.2 获取创作方案

9.3 确认创作方案

9.4 生成预览

9.5 确认预览

9.6 正式生成

9.7 获取项目素材

10. 订单支付接口

10.1 创建订单

10.2 获取支付状态

10.3 支付回调

11. 修改申请接口

11.1 提交修改申请

11.2 修改申请列表

12. 下载接口

12.1 获取下载链接

13. 后台接口示例

13.1 后台项目列表

13.2 后台项目详情

13.3 后台任务重试

13.4 后台任务终止

13.5 后台转人工

13.6 后台模板新增/编辑

13.7 后台 Provider 测试

14. WebSocket 进度推送

15. 权限规则

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

16.1 输出模式

16.2 身份锚点

16.3 人脸一致性质检

16.4 动作模板

16.5 真人动态视频片段

16.6 口型任务

8.4 KiB

Executable File

Raw Blame History