feat: support multi-image image generation

docs/api.md

@@ -21,7 +21,7 @@
 
 T-301 已实现对外 API 鉴权基线：`apps.api.authentication.ApiKeyAuthentication` 只解析 `Authorization: Bearer <API_KEY>`；生成、余额等外部 API 视图应继承 `apps.api.views.ExternalApiView`，不接受 Web session。
 
-T-302 已实现生成接口基线：`POST /api/v1/generate/title` 与 `POST /api/v1/generate/image` 已接入 API Key 鉴权、别名解析、计费规则、预扣点、Provider 调用、成功确认和失败退点；图片结果当前以本地 `MEDIA_ROOT` 保存并返回 `image_url`，后续可替换为对象存储。T-613 起内部实现已抽为生成核心 service，旧同步接口仍保持原字段、状态码和错误语义。T-614 起新增异步生图任务接口，提交阶段同步审核 prompt 和预扣点，worker 复用同一套已预扣执行 / 成功确认 / 失败退点阶段，不复制第二套资金逻辑。
+T-302 已实现生成接口基线：`POST /api/v1/generate/title` 与 `POST /api/v1/generate/image` 已接入 API Key 鉴权、别名解析、计费规则、预扣点、Provider 调用、成功确认和失败退点；图片结果当前以本地 `MEDIA_ROOT` 保存并返回 `image_url`，后续可替换为对象存储。T-613 起内部实现已抽为生成核心 service，旧同步接口仍保持原字段、状态码和错误语义。T-614 起新增异步生图任务接口，提交阶段同步审核 prompt 和预扣点，worker 复用同一套已预扣执行 / 成功确认 / 失败退点阶段，不复制第二套资金逻辑。T-620 起两个图生图接口都支持有序 `images`，服务端固定约定第 1 张为主商品图、后续图为参考图，旧单图字段保持兼容。
 
 T-619 已实现 `POST /api/v1/analyze/images`：使用独立 `vision` 操作和能力别名，同步接收一张或多张有序图片并返回完整文字。该接口复用 T-613 的准备 / 预扣 / 执行 / 成功确认 / 失败退点核心，不改变标题和生图接口。
 
@@ -228,7 +228,7 @@ X-Client-Version: 0.1.1
 {
   "prompt": "把这件衣服换成模特上身的穿搭图",
   "model": "image-hd",            // 能力别名，非具体模型名
-  "image_base64": "data:image/png;base64,...",  // 或 image_url；改图类模型(如映射到 gpt-image-2)原图必传
+  "image_base64": "data:image/png;base64,...",  // 旧单图字段：或 image_url；不可和 images 同时传
   "resolution": "1K",
   "aspect_ratio": "1:1",
   "parameters": {}                // 可选，安全供应商参数；未知字段/核心字段忽略
@@ -248,7 +248,22 @@ X-Client-Version: 0.1.1
 }
 ```
 
-要点：改图类模型缺原图返回 `bad_request`，不落 500；上游超时返回 `upstream_timeout`，其他上游失败返回 `upstream_error`，两者都**不最终扣点**（已预扣则退回）。T-604 后 prompt 命中本地敏感词时返回 `content_blocked`，并且不得下载 `image_url` 或解码大图后再拦截。T-612 后生图上游读取超时会受 `AI_IMAGE_UPSTREAM_DEADLINE_SECONDS` 硬截止保护，避免旧同步接口长期占用生成池线程。结果默认存对象存储返回 `image_url`，避免同步响应体过大。请求里的 `image_url` 适用同标题接口相同的 SSRF 防护和大小上限；内网图片请用 `image_base64`。
+多图请求示例（不要与旧单图字段混用）：
+
+```json
+{
+  "prompt": "为主商品图生成新的电商展示图",
+  "model": "image-hd",
+  "images": [
+    {"image_base64": "data:image/png;base64,..."},
+    {"image_url": "https://cdn.example.com/style-reference.jpg"}
+  ],
+  "resolution": "1K",
+  "aspect_ratio": "1:1"
+}
+```
+
+要点：`images` 必须为 1–`IMAGE_MAX_INPUT_IMAGES` 张的有序列表，每项必须且只能提供 `image_url` 或 `image_base64`。`images[0]` 是主商品图，`images[1:]` 只作为风格、构图、场景或排版参考；该规则由服务端追加，调用方 prompt 不能关闭或覆盖。改图类模型缺原图返回 `bad_request`，不落 500；新旧字段同时传、空列表或超限同样返回 `400 bad_request`。上游超时返回 `upstream_timeout`，其他上游失败返回 `upstream_error`，两者都**不最终扣点**（已预扣则退回）。T-604 后 prompt 命中本地敏感词时返回 `content_blocked`，并且不得下载 `image_url` 或解码大图后再拦截。T-612 后生图上游读取超时会受 `AI_IMAGE_UPSTREAM_DEADLINE_SECONDS` 硬截止保护，避免旧同步接口长期占用生成池线程。结果默认存对象存储返回 `image_url`，避免同步响应体过大。每个 `image_url` 都适用同标题接口相同的 SSRF 防护和大小上限；内网图片请用 `image_base64`。
 
 ### `POST /api/v1/generate/image/tasks`
 
@@ -268,7 +283,10 @@ Content-Type: application/json
 {
   "prompt": "把这件衣服换成模特上身的穿搭图",
   "model": "image-hd",
-  "image_base64": "data:image/png;base64,...",
+  "images": [
+    {"image_base64": "data:image/png;base64,..."},
+    {"image_url": "https://cdn.example.com/style-reference.jpg"}
+  ],
   "resolution": "1K",
   "aspect_ratio": "1:1",
   "parameters": {}
@@ -297,6 +315,7 @@ Content-Type: application/json
 - 提交阶段同步执行 prompt 审核；命中敏感词返回 `400 content_blocked`，不建任务、不扣点、不调上游。
 - 提交阶段预扣点数；余额不足返回 `402 insufficient_points`，不建任务。
 - `Idempotency-Key` 按当前 API Key 去重。同 key + 同 payload 返回同一 `task_id`，不重复扣点；同 key + 不同 payload 返回 `409 idempotency_conflict`。
+- `images` 与旧单个 `image_url` / `image_base64` 字段互斥；新数组保持提交顺序，第 1 张为主图、后续图为参考图。异步任务按顺序保存输入文件，旧单图任务仍可读取其历史 `input_image`。
 - 不保存 provider `raw`、上游密钥或 `image_base64` 原文；base64 会解码后作为输入文件引用保存，任务请求快照只保存必要字段和文件引用。
 - 桌面端主链路推荐传 `image_base64`。该路径在 submit 阶段只做解码和输入文件落盘，不发生外部网络请求，提交请求应保持短耗时。
 - `image_url` 仍按同步接口的 SSRF 与大小规则处理，并在 submit 阶段下载成输入文件引用；失败不扣点。这个路径可能因远程图片下载变慢而让 submit 阻塞，适合作为边缘兼容能力，不建议桌面端批量生图主流程使用。