lujiuyin/suixinkan_uikit
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 补充 AI 修图需求与接口说明

Browse Source
This commit is contained in:
lujiuyin
2026-08-13 09:16:39 +08:00
parent 05cfdc3662
commit 60502784db
2 changed files with 692 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
suixinkan/Features/TravelAlbum/AI修图接口文档.md
+524
View File
@@ -0,0 +1,524 @@
# AI 修图接口文档
## 接口列表
| # | 方法 | 路径 | 用途 |
|---|---|---|---|
| 1 | `GET` | `/api/yf-handset-app/photog/travel-album/material-list` | 获取相册网格素材和预览初始数据 |
| 2 | `GET` | `/api/yf-handset-app/photog/travel-album/material-info` | 获取/刷新当前原图及关联图 |
| 3 | `GET` | `/api/yf-handset-app/photog/travel-album/ai-retouch-options` | 获取 AI 模板、选择规则和剩余额度 |
| 4 | `POST` | `/api/yf-handset-app/photog/travel-album/ai-retouch` | 提交首次修图或重新修图任务 |
| 5 | `GET` | `/api/yf-handset-app/photog/travel-album/ai-retouch-job-info` | 查询 AI 修图任务进度和结果 |
| 6 | `POST` | `/api/yf-handset-app/photog/travel-album/delete-material` | 单张/批量删除素材及关联图 |
## 接口详情
### 获取相册素材列表
```http
GET /api/yf-handset-app/photog/travel-album/material-list?user_equity_travel_id=88&limit=30&cursor=opaque_cursor&sort=created_at_desc
```
| 参数 | 必填 | 说明 |
|---|---|---|
| `user_equity_travel_id` | 是 | 相册 ID |
| `limit` | 否 | 默认 30，最大 100 |
| `cursor` | 否 | 服务端返回的不透明游标，首页不传 |
| `sort` | 否 | `created_at_desc` 或 `created_at_asc` |
| `material_type` | 否 | `original`、`cover`；不传表示全部 |
响应：
```json
{
"code": 100000,
"msg": "success",
"data": {
"items": [
{
"id": "2031",
"user_equity_travel_id": "88",
"material_type": "original",
"original_asset": {
"id": "asset_8001",
"url": "https://cdn.example.com/albums/88/IMG_1024.jpg",
"thumbnail_url": "https://cdn.example.com/albums/88/IMG_1024_thumb.jpg",
"file_name": "IMG_1024.jpg",
"mime_type": "image/jpeg",
"file_size": 4821931,
"width": 4032,
"height": 3024,
"version": 1,
"created_at": "2026-08-09T01:00:00.000Z"
},
"display_status": "uploaded",
"variant_slots": [],
"revision": 7,
"created_at": "2026-08-09T01:00:00.000Z",
"updated_at": "2026-08-11T07:30:18.000Z"
}
],
"next_cursor": "next_opaque_cursor",
"has_more": true
}
}
```
- 只返回网格顶层素材：原图和独立封面。
- 原图如存在关联图，`variant_slots` 包含预览页 Tab 初始数据。
- 建议使用游标分页，因为 AI 任务完成时可能实时插入封面素材。
### 获取/刷新单个原图项目
```http
GET /api/yf-handset-app/photog/travel-album/material-info?user_equity_travel_id=88&material_id=2031
```
查询参数 `user_equity_travel_id` 和 `material_id` 均必填。响应的 `data` 直接返完整 `material_project`，字段与列表 Item 完全一致。该接口供预览页刷新和提交后定向更新使用。
如 `material_id` 已删除，返回 `404 MATERIAL_NOT_FOUND`。
### 获取 AI 修图选项
```http
GET /api/yf-handset-app/photog/travel-album/ai-retouch-options?user_equity_travel_id=88&scope=batch&source_count=4
```
| `scope` | 使用场景 |
|---|---|
| `batch` | 网格多选 AI 修图 |
| `all_variants` | 预览页无 Tab，或当前是原图 Tab |
| `refined_only` | 当前是精修后 Tab |
| `atmosphere_only` | 当前是氛围感 Tab |
`user_equity_travel_id`、`scope` 和 `source_count` 均必填。`source_count` 用于计算封面模板是否显示和必选。
响应：
```json
{
"code": 100000,
"msg": "success",
"data": {
"scope": "batch",
"source_count": 4,
"groups": [
{
"type": "refined",
"title": "原图精修",
"required": true,
"selection_mode": "single",
"quota_cost": {
"mode": "per_source",
"units": 1
},
"templates": [
{
"id": "tpl_refined_12",
"name": "清透精修",
"preview_url": "https://cdn.example.com/templates/refined_12.jpg",
"enabled": true
}
]
},
{
"type": "atmosphere",
"title": "氛围感修图",
"required": false,
"selection_mode": "single",
"quota_cost": {
"mode": "per_source",
"units": 1
},
"templates": [
{
"id": "tpl_atmosphere_06",
"name": "暖阳",
"preview_url": "https://cdn.example.com/templates/atmosphere_06.jpg",
"enabled": true
}
]
},
{
"type": "cover",
"title": "封面风格模板",
"required": true,
"selection_mode": "single",
"quota_cost": {
"mode": "per_job",
"units": 0
},
"templates": [
{
"id": "tpl_cover_03",
"name": "旅行画册",
"preview_url": "https://cdn.example.com/templates/cover_03.jpg",
"enabled": true
}
]
}
],
"quota": {
"unit": "retouch_time",
"remaining": 12,
"reserved": 3,
"display_text": "剩余 12 次",
"updated_at": "2026-08-11T07:29:58.000Z"
},
"limits": {
"minimum_source_count": 1,
"maximum_source_count": 50,
"cover_minimum_source_count": 4
}
}
}
```
设计要点：
- 不再让 App 传 `scenic_id`，后端从相册归属景区获取可用模板。
- 由后端返回 `required` 和可见分组，避免多端各写一套“4 张显示封面”规则。
- 客户端可默认选中必选分组的第一个可用模板，可选分组默认不选。
- 此接口用于 UI 配置；提交时后端仍必须根据真实素材 ID 重新校验。
- 同一响应返回当前用户的剩余可用额度和每类输出的额度单价，弹窗无需再发起第二个额度请求。
- `quota.remaining` 是扣除其他未完成任务已预占数量后、当前立即可用的额度；弹窗底部使用此值显示“剩余 N 次”。
- 额度文案位于模板选择弹窗的固定底部区域，不随中间模板列表滚动。
- `quota.reserved` 是当前用户其他未完成任务的预占额度，仅用于解释账户状态。
- 客户端预估本次消耗时，对已选输出求和：`per_source` 类型为 `source_count * units`，`per_job` 类型为 `units`。封面始终为 0。
- 本文档默认精修和氛围感每生成一张各消耗 1 次。如实际商业规则变更，后端只需调整 `quota_cost`，客户端不需改接口。
### 创建 AI 修图任务
```http
POST /api/yf-handset-app/photog/travel-album/ai-retouch
Idempotency-Key: 9A7820CE-78AB-45C6-9E0F-5DF268995379
Content-Type: application/json
```
#### 5.4.1 网格批量修图
```json
{
"user_equity_travel_id": "88",
"scope": "batch",
"source_material_ids": ["2031", "2032", "2033", "2034"],
"outputs": [
{
"type": "refined",
"template_id": "tpl_refined_12"
},
{
"type": "atmosphere",
"template_id": "tpl_atmosphere_06"
},
{
"type": "cover",
"template_id": "tpl_cover_03"
}
]
}
```
#### 5.4.2 预览页原图 Tab
```json
{
"user_equity_travel_id": "88",
"scope": "all_variants",
"source_material_ids": ["2031"],
"outputs": [
{
"type": "refined",
"template_id": "tpl_refined_15"
},
{
"type": "atmosphere",
"template_id": "tpl_atmosphere_09"
}
]
}
```
如用户未选氛围感模板，`outputs` 中不传 `atmosphere`。缺失表示“本次不处理”，不表示删除现有氛围感图。
#### 5.4.3 只重新精修
```json
{
"user_equity_travel_id": "88",
"scope": "refined_only",
"source_material_ids": ["2031"],
"outputs": [
{
"type": "refined",
"template_id": "tpl_refined_18"
}
]
}
```
#### 5.4.4 只重新生成氛围感
```json
{
"user_equity_travel_id": "88",
"scope": "atmosphere_only",
"source_material_ids": ["2031"],
"outputs": [
{
"type": "atmosphere",
"template_id": "tpl_atmosphere_11"
}
]
}
```
#### 5.4.5 提交校验矩阵
| `scope` | 原图数 | 精修 | 氛围感 | 封面 |
|---|---:|---|---|---|
| `batch` | 1 至 50 | 必选 | 可选 | 少于 4 张禁止；4 张及以上必选 |
| `all_variants` | 必须为 1 | 必选 | 可选 | 禁止 |
| `refined_only` | 必须为 1 | 必选 | 禁止 | 禁止 |
| `atmosphere_only` | 必须为 1 | 禁止 | 必选 | 禁止 |
另外：
- `source_material_ids` 必须去重，且全部为 `original` 类型。
- 模板必须启用、类型匹配，且适用于相册所属景区。
- 后端必须使用提交时的最新额度计费规则重新计算消耗，不信任客户端的预估数值。
- 封面输出不论首次生成、重试或任务结果如何，额度消耗始终为 0。
- 每个输出槽位均采用 `replace_on_success`：成功后替换旧版本，失败保留旧版本。
- 批量选中已有 AI 结果的原图时，允许重新生成，只覆盖本次 `outputs` 列出的类型。
- 同一原图、同一槽位已有 `queued/processing` 任务时，整次请求返回 `409 RETOUCH_TARGET_BUSY`，并列出冲突项。
#### 5.4.6 提交响应
HTTP 状态码：`202 Accepted`
```json
{
"code": 100000,
"msg": "AI 修图任务已提交",
"data": {
"job": {
"id": "job_01K2E4",
"user_equity_travel_id": "88",
"scope": "all_variants",
"status": "queued",
"source_material_ids": ["2031"],
"progress": {
"total": 2,
"queued": 2,
"processing": 0,
"succeeded": 0,
"failed": 0
},
"created_at": "2026-08-11T07:30:15.123Z",
"started_at": null,
"finished_at": null
},
"quota_reservation": {
"before_remaining": 12,
"reserved_units": 2,
"remaining_after_reservation": 10,
"cover_units": 0
},
"affected_projects": [
{
"id": "2031",
"user_equity_travel_id": "88",
"material_type": "original",
"original_asset": {
"id": "asset_8001",
"url": "https://cdn.example.com/albums/88/IMG_1024.jpg",
"thumbnail_url": "https://cdn.example.com/albums/88/IMG_1024_thumb.jpg",
"file_name": "IMG_1024.jpg",
"mime_type": "image/jpeg",
"file_size": 4821931,
"width": 4032,
"height": 3024,
"version": 1,
"created_at": "2026-08-09T01:00:00.000Z"
},
"display_status": "pending",
"variant_slots": [
{
"type": "refined",
"asset": null,
"latest_generation": {
"job_id": "job_01K2E4",
"status": "queued",
"is_replacement": false,
"template": {
"id": "tpl_refined_15",
"name": "自然精修"
},
"requested_at": "2026-08-11T07:30:15.123Z",
"started_at": null,
"finished_at": null,
"error": null
}
},
{
"type": "atmosphere",
"asset": null,
"latest_generation": {
"job_id": "job_01K2E4",
"status": "queued",
"is_replacement": false,
"template": {
"id": "tpl_atmosphere_09",
"name": "暖阳"
},
"requested_at": "2026-08-11T07:30:15.123Z",
"started_at": null,
"finished_at": null,
"error": null
}
}
],
"revision": 8,
"created_at": "2026-08-09T01:00:00.000Z",
"updated_at": "2026-08-11T07:30:15.123Z"
}
]
}
}
```
必须返回 `job.id`、`quota_reservation` 和更新后的 `affected_projects`。客户端用 `remaining_after_reservation` 立即更新剩余额度，并更新 Cell 状态；已有 `asset` 的重修 Tab 可同步显示处理态，首次生成且 `asset = null` 的槽位不显示 Tab。
### 查询 AI 修图任务
```http
GET /api/yf-handset-app/photog/travel-album/ai-retouch-job-info?user_equity_travel_id=88&job_id=job_01K2E4
```
响应：
```json
{
"code": 100000,
"msg": "success",
"data": {
"id": "job_01K2E4",
"user_equity_travel_id": "88",
"scope": "batch",
"status": "partially_succeeded",
"source_material_ids": ["2031", "2032", "2033", "2034"],
"progress": {
"total": 9,
"queued": 0,
"processing": 0,
"succeeded": 8,
"failed": 1
},
"quota_settlement": {
"status": "settled",
"reserved_units": 8,
"consumed_units": 7,
"released_units": 1,
"cover_units": 0
},
"targets": [
{
"source_material_id": "2031",
"output_type": "refined",
"status": "succeeded",
"result_asset_id": "asset_9201",
"error": null
},
{
"source_material_id": "2032",
"output_type": "atmosphere",
"status": "failed",
"result_asset_id": null,
"error": {
"code": "AI_PROVIDER_TIMEOUT",
"message": "AI 服务处理超时，请重试",
"retryable": true
}
},
{
"source_material_id": null,
"output_type": "cover",
"status": "succeeded",
"result_material_id": "cover_301",
"error": null
}
],
"created_at": "2026-08-11T07:30:15.123Z",
"started_at": "2026-08-11T07:30:18.000Z",
"finished_at": "2026-08-11T07:33:00.000Z"
}
}
```
| 整体状态 | 含义 |
|---|---|
| `queued` | 已受理，尚无子任务开始 |
| `processing` | 至少一个子任务正在执行，且尚未全部完成 |
| `succeeded` | 所有子任务成功 |
| `partially_succeeded` | 子任务全部结束，且既有成功也有失败 |
| `failed` | 子任务全部结束，没有任何成功结果 |
| `canceled` | 任务因素材删除或管理操作被取消 |
额度结算规则：
- 任务提交成功时先预占所有非封面子任务的额度，封面不进入预占。
- 每个精修/氛围感子任务成功后，将对应预占转为实际消耗。
- 子任务失败或取消时释放对应预占。因此部分成功示例中，预占 8 次、成功消耗 7 次、失败退回 1 次。
- `quota_settlement.status` 取值为 `reserved | partially_settled | settled`。
客户端如只关心当前预览图，优先调用单素材接口；本接口主要用于批量进度、问题排查和任务详情。
### 批量删除素材
```http
POST /api/yf-handset-app/photog/travel-album/delete-material
Content-Type: application/json
```
请求：
```json
{
"user_equity_travel_id": "88",
"material_ids": ["2031", "2032", "cover_301"]
}
```
为兼容旧客户端，原单张请求体继续有效：
```json
{
"id": "2031"
}
```
新请求使用 `user_equity_travel_id + material_ids`，旧请求使用 `id`，两组参数不同时传入。
响应：
```json
{
"code": 100000,
"msg": "删除成功",
"data": {
"deleted_material_ids": ["2031", "2032", "cover_301"],
"deleted_variant_asset_ids": ["asset_9101", "asset_9102"],
"canceled_job_ids": ["job_01K2E4"],
"oss_cleanup_status": "scheduled"
}
}
```
语义：
- 传入原图 ID：级联软删除精修图、氛围感图，并取消该原图的未完成子任务。
- 传入独立封面 ID：只删除该封面素材。
- 删除原图不级联删除以它为输入之一的已生成封面。
- 数据库业务删除采用一个事务，默认全部成功或全部失败。
- 任一 ID 不属于当前相册或无权删除时，整次请求失败。已删除的 ID 可视为幂等成功。
- OSS 文件清理异步执行，不影响业务删除成功。