docs/SPEC_WEB_UI.md

# Web UI — product specification

**What to build:** this file. **How to run / deploy:** [WEB_DEV_GUIDE.md](./WEB_DEV_GUIDE.md).

## Overview

Image and video generation from prompts and optional reference images.

## AI 创作台

**A. 图片** — 0–3 张参考图 + 提示词 → 一张图。模型含 Nano Banana（`gemini-2.5-flash-image`，无长思考）、Nano Banana 2（`gemini-3.1-flash-image-preview`，可选长思考）、Nano Banana Pro（`gemini-3-pro-image-preview`，长思考）；默认选项为 Nano Banana 2 快速。宽高比、分辨率见 `generation_options.json`。

**B. 视频** — 0–3 张参考图 + 提示词 → 短视频。Veo 模型可配置；**Veo 3 / Veo 3 Fast** 与 **Veo 3.1 Lite** 为 **`supports_reference_images: false`**（前两者仅纯提示词）。默认模型 **Veo 3.1 Fast**。有参考图时时长 **8s**；仅文案时 4/6/8s（以 API 为准）。

**C. 首尾过渡** — 起始帧必填 + 提示词；时长 **固定 8s**。**Veo 3 / Veo 3 Fast**（`supports_end_frame: false`）仅起始帧；**Veo 3.1** 可选独立结尾帧或「与起始相同」。默认模型 **Veo 3.1 Fast**。

## 辅助工具

- **超分辨率：** 单张原图 → 高清图；默认提示词可改；宽高比按原图自动建议（表单底部可改）；比例不匹配时警告仍可生成。
- **提取视频帧：** 本地视频 → 时间轴选帧 → PNG。
- **图像裁剪：** 前端 Canvas，不上传服务器；自由或固定比例 → PNG。
- **替换纯色背景：** 前端 Canvas；原/目标色、容差、预览与 PNG。

## 示例

静态演示（预置素材），不调用模型。

## 仓库脚本

`run_gen_image_*.sh`、`run_gen_video_*.sh` 等可能只覆盖简化场景。API 文档：[图片](https://ai.google.dev/gemini-api/docs/image-generation?hl=zh-cn)、[视频](https://ai.google.dev/gemini-api/docs/video?hl=zh-cn)。

## 界面

- 密码登录（`WEB_UI_PASSWORD`）。
- 侧栏进入各功能；提示词必填；参考图规则按 A/B/C；生成中显示耗时。
- 模型名、分辨率、宽高比等来自 **`web/config/generation_options.json`**（可用 **`GENERATION_OPTIONS_PATH`**），避免写死在代码里；改 JSON 通常不必重编前端。

## 其他

- `GEMINI_API_KEY` 仅环境变量，勿入库。
- 代码英文为主；界面与提示词可用中文。