# 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 层与前端契约无需改动。