feat: 开发编辑工作台

2026-08-14 18:27:45 +08:00
parent b27e42dc75
commit c18d70017e
50 changed files with 5496 additions and 57 deletions
@@ -0,0 +1,71 @@
+# AI 图生图（wanx2.1-imageedit）
+
+「发布工作台」（`studio/`）当前唯一的页面：上传多张图片 → 加水印（文字/图片）→ 对单张图片调用
+万相 2.1 通用图像编辑模型做图生图。
+
+## 目录与职责
+
+| 位置 | 职责 |
+|---|---|
+| `studio/src/pages/ai-image/` | 页面：上传、水印设置、预览网格、AI 弹窗 |
+| `studio/src/pages/ai-image/components/WatermarkCanvas.tsx` | 单图可拖拽水印画布 |
+| `studio/src/pages/ai-image/components/ImageEditModal.tsx` | 图生图弹窗（上：原图/生成对比；下：对话框） |
+| `studio/src/utils/watermark.ts` | 水印绘制（移植自 `web/js/app.js`，坐标相对原图） |
+| `studio/src/services/image.ts` | 前端调用后端 `/api/image/edit` |
+| `server/api/image.py` | 路由 `POST /api/image/edit` |
+| `server/services/image_edit.py` | 万相模型调用（同步 SDK 在线程池执行） |
+| `server/schemas/image_edit.py` | 请求/响应 Pydantic 模型 |
+
+## 接口契约
+
+`POST /api/image/edit`
+
+请求（JSON）：
+
+```json
+{
+  "base_image": "data:image/png;base64,... | https://...",
+  "prompt": "把背景换成纯白色摄影棚",
+  "function": "description_edit",
+  "n": 1,
+  "size": "",
+  "seed": null,
+  "style": "",
+  "prompt_extend": true,
+  "strength": 0.8
+}
+```
+
+- `base_image`：前端把「已加水印」的当前图片以 data URL 传入（data URL 与公网 URL 二选一）。
+- `function` 白名单：`description_edit`（文本指令编辑）、`description_edit_with_mask`（局部重绘，需 `mask_image`）、
+  `stylization_local`、`stylization_all`。默认 `description_edit`。
+- `prompt_extend`：是否自动扩写提示词，官方示例默认开启（默认 `true`）。
+- `strength`：修改幅度 0.0~1.0，官方默认 0.5（值越小越接近原图）。
+  **新增文字、大幅修改等场景建议调高到 0.8 左右**，否则模型可能因"贴近原图"而忽略新内容。
+
+响应：
+
+```json
+{
+  "task_id": "6e319d88-...",
+  "results": [{ "url": "https://...oss-cn-wulanchabu...png?...", "image_base64": "data:image/png;base64,..." }],
+  "image_count": 1,
+  "request_id": "dc41682c-..."
+}
+```
+
+> `url` 有效期 24 小时。`image_base64` 为服务端代下载的 data URL，前端可据此直接合成/导出，
+> 规避阿里云结果 URL 未开放 CORS 导致的画布污染（无法 toDataURL）。
+
+## 密钥与地域
+
+- 模型：`wanx2.1-imageedit`，仅支持**华北 2（北京）**地域的 API Key。
+- 密钥：`.env` 中的 `DASHSCOPE_API_KEY`。
+- 业务空间调用时，另配 `DASHSCOPE_BASE_HTTP_API_URL=https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1`；
+  普通 API Key 调用留空。
+
+## 关于图片存储
+
+当前服务端**不做图片存储**：前端直接把 base64 图片传给模型，结果 URL 原样返回给前端展示。
+后续接入七牛云时，可在 `services/image_edit.py` 拿到 `results[].url` 后增加「下载 → 转存七牛 → 返回新 URL」一步，
+api 层与前端契约无需改动。