feat: AI炫图接入gpt-image-2.5云端生图(结构化提示词工程+照片参考合成)

doc/API.md

@@ -465,3 +465,17 @@ uv run uvicorn huamenchuang.main:app --reload   # 启动，http://localhost:8000
 - 流程：上传场景照片 → 拖拽框选窗洞（原始照片坐标）→ 选样板窗型 → `renderWindowOnly`（分割树重放渲染透明背景窗型：玻璃渐变/中梃/扇框开向/装饰格条）→ 光照匹配（采样洞口周边亮度调整窗户亮度）→ 边缘贴合 → 场景后处理（安装投影/擦除填充/暖色滤镜/石材基座/背景虚化/去饱和毛坯）
 - 一键生成 4 方案画廊 + PNG 下载；原"风格速览"模式保留为第二 Tab
 - 无新增后端接口（复用 `/api/windoor/templates` 与 `/api/rendering-info`）
+
+### 12.23 云端 AI 生图 `/api/ai-render`（v2.28 新增，gpt-image-2.5）
+
+接入 OpenAI Images 兼容中转站（`geminiapi.ai`，模型 `gpt-image-2.5-1k`）。**Key 仅存后端**（`.env` 的 `HMC_AI_API_KEY`，已 gitignore；Docker 部署用环境变量注入）。
+
+**提示词工程**（`services/ai_prompt.py`，核心资产）：从 `drawing_data` 结构化提取窗型特征（组合单元数/每单元宽高 mm/玻璃格数/扇类型（平开、推拉、内开内倒、对开门）/开向内外/纱扇/圆弧复古/装饰格条）→ 生成专业英文提示词：主体先行（窗型几何量化描述）→ 材质风格（4 风格映射铝型材 finish）→ 摄影光照（3 时间）→ 负面约束（"保持窗型分格不变，勿增删扇"）→ 质量词。生成尺寸按窗型宽高比自动选择（1024x1024 / 1536x1024 / 1024x1536）。
+
+| 接口名称 | 方式 | URL 路径 | 请求参数 | 说明 |
+|---|---|---|---|---|
+| 提示词预览 | POST | `/api/ai-render/prompt` | `{template_id\|drawing_data, style, time, scene}` | 返回 `{features(窗型特征), prompt(优化后完整提示词), size}` |
+| **云端生成** | POST | `/api/ai-render/generate` | `{template_id\|drawing_data, mode: quick\|photo, style, time, scene, photo_b64?}` | quick→`images/generations`；photo→`images/edits`（用户照片为参考图，AI 将窗型合成进照片窗洞）；返回 `{image_b64, prompt, size, features}`；耗时 30~90s（前端 timeout 200s） |
+
+- 未配置 Key 时接口返回 code=0，前端降级本地程序化渲染（"本地 4 方案"按钮）
+- 前端：AI 炫图页两个模式（照片合成/风格速览）主按钮均走云端生成，结果大图展示 + 提示词折叠面板可查看 + PNG 下载；照片模式参考图自动压缩 ≤1536px JPEG