Upload folder using huggingface_hub

Dockerfile

@@ -30,4 +30,7 @@ COPY --from=frontend-build /app/web/backend/static /app/web/backend/static
 
 EXPOSE 7860
 
-CMD ["sh", "-c", "exec uvicorn web.backend.main:app --host 0.0.0.0 --port ${PORT:-7860}"]
+# Trust reverse-proxy headers (X-Forwarded-Proto). Default allow-list is 127.0.0.1 only;
+# HF Spaces sits behind a proxy — without this, the app thinks the request is HTTP and
+# session cookies often fail, so login loops.
+CMD ["sh", "-c", "exec uvicorn web.backend.main:app --host 0.0.0.0 --port ${PORT:-7860} --forwarded-allow-ips='*'"]

README.md

@@ -9,27 +9,21 @@ pinned: false
 
 # Gemini Studio Web
 
-Gemini 图片 / 视频创作台（FastAPI + React）。本仓库根目录的 **`README.md`** 是**总索引**（并供 Hugging Face Spaces 读取 YAML 元数据）；具体说明拆到 `docs/` 下，避免与「给实现者的需求文档」「给开发者的运行手册」混在一起。
+Gemini 图片 / 视频 Web 应用（FastAPI + React）。根目录 `README.md` 含 Hugging Face Spaces 的 YAML 头；详细说明见 `docs/`。
 
 ## Documentation
 
-| Document | Audience | Contents |
-|----------|----------|----------|
-| [**docs/SPEC_WEB_UI.md**](docs/SPEC_WEB_UI.md) | 产品 / 实现者 / AI | 功能范围、界面与示例页要求、非技术约束（原 `PLAN.md`） |
-| [**docs/WEB_DEV_GUIDE.md**](docs/WEB_DEV_GUIDE.md) | 本机与部署的开发者 | 环境、`PYTHONPATH`、环境变量、`generation_options.json`、本地运行、稳定 URL、Docker、Hugging Face（原 `web/README.md`） |
+| Document | Contents |
+|----------|----------|
+| [**docs/SPEC_WEB_UI.md**](docs/SPEC_WEB_UI.md) | 功能与界面规格（原 PLAN） |
+| [**docs/WEB_DEV_GUIDE.md**](docs/WEB_DEV_GUIDE.md) | 环境、部署、Hugging Face |
 
-在 GitHub 里浏览 `docs/` 文件夹时，可先打开 **[docs/README.md](docs/README.md)**（仅索引，内容与上表一致）。
+索引：[docs/README.md](docs/README.md)。
 
 ---
 
-## Hugging Face Space
+## Hugging Face（摘要）
 
-部署到 Space 后，在 **Settings → Variables and secrets** 中配置（名称区分大小写）。保存后 Space 会重启；首次冷启动可能需一两分钟。
+上传、`README` 元数据、Secrets、本地 Docker：见 **[docs/WEB_DEV_GUIDE.md §10](docs/WEB_DEV_GUIDE.md#10-hugging-face-spaces-docker)**。
 
-| Name | 说明 |
-|------|------|
-| `GEMINI_API_KEY` | Google AI Studio / Gemini API 密钥（仅服务端使用） |
-| `WEB_UI_PASSWORD` | 登录本站时输入的密码 |
-| `SESSION_SECRET` | 会话签名用随机串，例如本地执行 `openssl rand -hex 32` 生成 |
-
-更完整的步骤与 `docker run` 自测见 **[docs/WEB_DEV_GUIDE.md §10](docs/WEB_DEV_GUIDE.md#10-hugging-face-spaces-docker)**。可选变量 `GENERATION_OPTIONS_PATH` 等见该文档 **§3–4**。
+Space **Settings → Variables and secrets** 至少配置：`GEMINI_API_KEY`、`WEB_UI_PASSWORD`、`SESSION_SECRET`（大小写一致，含义见 §10.4 与 §3）。

docs/README.md

@@ -1,8 +1,8 @@
 # Documentation
 
-| File | Role |
-|------|------|
-| [SPEC_WEB_UI.md](./SPEC_WEB_UI.md) | Product / implementation specification |
-| [WEB_DEV_GUIDE.md](./WEB_DEV_GUIDE.md) | Developer runbook (local run, env, Docker, Hugging Face) |
+| File | Contents |
+|------|----------|
+| [SPEC_WEB_UI.md](./SPEC_WEB_UI.md) | Product spec |
+| [WEB_DEV_GUIDE.md](./WEB_DEV_GUIDE.md) | Runbook (local, env, Docker, HF §10) |
 
-Hub (overview + HF secrets summary): **[README.md](../README.md)**.
+Overview: [README.md](../README.md).

docs/SPEC_WEB_UI.md

@@ -1,113 +1,72 @@
 # Web UI — product specification
 
-This file is the **authoring / product spec** for turning the repo into a web UI: what to build, feature scope, and UX expectations. It is aimed at **implementers and AI assistants**. For how to run the stack, env vars, and deployment, see **[`WEB_DEV_GUIDE.md`](./WEB_DEV_GUIDE.md)**.
+**Scope:** what to build and UX expectations (implementers / AI). **How to run / deploy:** [WEB_DEV_GUIDE.md](./WEB_DEV_GUIDE.md).
 
 ---
 
-This is the initial plan for how to change this pure code-based repo to a web ui.
-
 # Overview
-The final version of this repo should be launched as a web ui, which supports image and video generation.
-The user might upload prompts and images (optional) as condition. 
-There will be several main features:
-
-## 第一板块：AI创作台
-- A. 图片生成或编辑：提供0-3张参考图片和提示词，生成一张图
-    - 思考强度：界面**并列三项**（模型 + 强度合一）——Flash（快速，默认 minimal）、Flash（快速）（长思考，high）、Pro（标准）（长思考，high）；对应 `gemini-3.1-flash-image-preview` / `gemini-3-pro-image-preview` + `thinking_level`
-    - 宽高比："1:1","2:3","3:2","3:4","4:3","4:5","5:4","9:16","16:9","21:9"
-    - 分辨率："1K", "2K", "4K"
-- B. 视频生成：提供0-3张参考图片和提示词，生成一个短视频
-    - 模型（可配置，见 `generation_options.json`）：`veo-3.1-generate-preview`、`veo-3.1-lite-generate-preview`、`veo-3.1-fast-generate-preview`；界面标注为 **（标准）/（轻量）/（快速）**；其中 **Lite 不支持参考图**（由 `supports_reference_images` 标注）
-    - 宽高比：16:9 或 9:16
-    - 分辨率：720p、1080p 或 4k
-    - 时长：纯文案时可 4/6/8 秒（与分辨率组合以 API 为准）；**有参考图时固定 8 秒**（Veo 接口要求）
-- C. 视频生成（首尾过渡）（起始/可选结尾帧）：至少 1 张起始帧 + 提示词，生成一个短视频；结尾帧可选，或勾选「结尾与起始相同」
-    - 模型：与 B 相同，同上三项 Veo 预览模型，可配置
-    - 宽高比：16:9 或 9:16
-    - 分辨率：720p、1080p 或 4k
-    - 时长：固定 **8 秒**（首/尾帧条件时 Veo 不接受 4/6 秒，与纯文案视频不同）
 
+Web UI for image and video generation: prompts plus optional reference images.
 
-## 第二板块：辅助工具
+## 第一板块：AI 创作台
 
-- 超分辨率：
-    - 内在调用与「图片编辑或生成」相同，使用 1 张参考图生成更高清图片
-    - 提示词**默认**为「保持内容完全不变，提高图片的分辨率」，**可修改**
-    - **先上传原图（必填）**；根据原图**宽高比**在配置列表中**自动择近匹配**；**宽高比选项放在表单最下**，可手动改
-    - **分辨率**默认 4K，**不**根据原图自动推断，用户自选 1K/2K/4K
-    - 若原图宽高比与列表中**任一项都不接近**，界面**警告**：生成图可能与原图不完全一致，仍可点击生成
-    - 模型**默认「快速」**，可改为「标准」
-
-- 提取视频的特定帧：
-    - 用户上传一个视频
-    - 视频将出现一个胶片一样可以拉动的进度条，用户随便停在一个位置，展示具体的时间和对应图像的preview
-    - 一旦点击“下载”，在下方讲出现这一帧作为一张单独的图片，可供用户下载。
-
-- 图像裁剪（**前端 Canvas**，`/tools/crop`，不上传服务器）
-    - 上传图片，**交互式裁剪框**（框内平移、四角缩放；「自由」下四边为**可见白条**可拖，命中区与光标反馈按画布像素计算）
-    - 可选固定比例：与 `generation_options.json` 中**图片宽高比**列表一致（另加「自由」）；切换比例时重置为居中最大适配框
-    - 裁剪交互区即原图；裁剪结果随框**实时**更新，下载 PNG
-
-- 替换纯色背景（**前端 Canvas**，`/tools/replace-bg`，不上传服务器）
-    - 用户上传一个图片（提示：仅适合**纯色或大块相近色**背景）
-    - **原始色 / 目标色**的设定方式一致：**系统调色板**（原生取色器，通常含放大镜/吸管）、**手动** R/G/B 或 Hex（可「应用 Hex」）；可选在预览图上点击取像素色
-    - **不透明度** 0–100%（默认 100%，仅作用于替换结果）
-    - 与原始色在 RGB 距离 ≤ **容差** 的像素改为目标 RGBA（容差可调）
-    - 下方预览，可下载 PNG
+**A. 图片生成或编辑** — 0–3 张参考图 + 提示词 → 一张图。
 
-## 第三板块：示例
-这一类是上述创作台的**简化和示例**版本，例如，已经为你写好提示词，选定各种参数，输入参考图片（这里来自asset/目录，有待添加），展示输出。
-理论上，你用上面的创作台能达到完全一样的效果，只是这里给了你例子。因此这个页面是完全静止的，不涉及model query。
+- 思考强度：三项并列（模型 + 强���）— Flash（快速，默认 minimal）、Flash（长思考，high）、Pro（长思考，high）；对应 `gemini-3.1-flash-image-preview` / `gemini-3-pro-image-preview` + `thinking_level`。
+- 宽高比：`1:1` … `21:9`（见 `generation_options.json`）。
+- 分辨率：`1K` / `2K` / `4K`。
 
-简介：Wake-UP人声乐团是北京大学2025-2026年度十佳歌手冠军，他们比赛现场的彩幕制作过程使用了如下功能。
+**B. 视频生成** — 0–3 张参考图 + 提示词 → 短视频。
 
-1. 手写字体生成
-- 展示两张output
+- 模型（可配置）：`veo-3.1-generate-preview`、`veo-3.1-lite-generate-preview`、`veo-3.1-fast-generate-preview`；界面：**（标准）/（轻量）/（快速）**。Lite **不支持参考图**（`supports_reference_images`）。
+- 宽高比：16:9 或 9:16；分辨率：720p / 1080p / 4k。
+- 时长：纯文案 4/6/8 秒（与分辨率以 API 为准）；**有参考图时固定 8 秒**。
 
-2. 在图片上加文字
-- 展示提示词、一张input和output
+**C. 视频生成（首尾过渡）** — 至少 1 张起始帧 + 提示词；结尾帧可选或「与起始相同」。
 
-3. 循环视频制作
-- 展示提示词、一张input和output video
+- 模型：同 B；宽高比、分辨率：同 B。
+- 时长：**固定 8 秒**（首/尾帧条件不接受 4/6 秒）。
 
-4. 图像超分辨率
-- 展示一张input和output
+## 第二板块：辅助工具
+
+- **超分辨率：** 与图片编辑同一路径，1 张参考图 → 更高清；默认提示词可改。先上传原图（必填）；按原图宽高比在列表中自动择近匹配，**宽高比控件放在表单最下**、可手改。分辨率默认 4K（不随原图自动推断），自选 1K/2K/4K。原图比例与列表都不接近时 **警告**，仍可生成。模型默认「快速」，可改「标准」。
+- **提取视频帧：** 上传视频 → 可拖动时间轴 → 预览时间与画面 → 「下载」导出该帧 PNG。
+- **图像裁剪**（前端 Canvas，`/tools/crop`，不上传服务器）：裁剪框可平移、四角缩放；「自由」比例下四边白条可拖；固定比例选项与图片宽高比列表一致（另加「自由」）；裁剪区即原图、结果实时更新；下载 PNG。
+- **替换纯色背景**（前端 Canvas，`/tools/replace-bg`）：适合纯色或大块相近背景；原色/目标色（系统调色板、手动 R/G/B 或 Hex、预览图点击取色）；不透明度 0–100%；RGB 距离 ≤ 容差的像素替换为目标色；预览与 PNG 下载。
+
+## 第三板块：示例
 
-5. 视频延伸（长视频生成）
-只展示output，说此功能敬请期待（保持神秘）
+创作台的静态示例：预置提示词与 `assets/` 素材，展示输出；不调用模型。
 
+简介：Wake-UP 人声乐团（北大 2025–2026 十佳歌手冠军）比赛彩幕相关能力展示。
 
-# 示例代码
-所有上述功能都有一个或多个初步的纯代码脚本
-- A. 参考 /Users/lehongwu/Projects/others/lyrics/VideoGeneration-release/run_gen_image_image_cond.sh 和 /Users/lehongwu/Projects/others/lyrics/VideoGeneration-release/run_gen_image_prompt_only.sh
+1. 手写字体：两张 output。  
+2. 图上加字：提示词 + input + output。  
+3. 循环视频：提示词 + input + output 视频。  
+4. 超分辨率：input + output。  
+5. 视频延伸（长视频）：仅 output +「敬请期待」。
 
-- B. 参考 /Users/lehongwu/Projects/others/lyrics/VideoGeneration-release/run_gen_video_prompt_only.sh
+## 示例脚本（仓库内）
 
-- C. 参考 /Users/lehongwu/Projects/others/lyrics/VideoGeneration-release/run_gen_video_image_start_end_diff.sh
+- A：`run_gen_image_image_cond.sh`、`run_gen_image_prompt_only.sh`
+- B：`run_gen_video_prompt_only.sh`
+- C：`run_gen_video_image_start_end_diff.sh`
 
-注意，上述代码不一定包含完整功能，例如，只输入一张图片，而不是0-3张。对于完整document和例子，都参考如下网站：
-https://ai.google.dev/gemini-api/docs/image-generation?hl=zh-cn
-https://ai.google.dev/gemini-api/docs/video?hl=zh-cn
+脚本可能只覆盖单图等简化场景。完整 API 说明：[图片](https://ai.google.dev/gemini-api/docs/image-generation?hl=zh-cn)、[视频](https://ai.google.dev/gemini-api/docs/video?hl=zh-cn)。
 
 # 界面要求
-- 初始有一个输入密码界面，这个密码是launch网站之前由用户设置的环境变量
-- 密码正确后，侧栏有上述多重feature选项，点开其中任意一个，包含：
-    1. 功能简介和指示
-    2. 输入提示词的窗口（不可以为空）
-    3. 留给用户上传图片的空位（feature A/B 有三个参考图空位，均可空；feature C 有起始帧必填、结尾帧可选，并可勾选与起始相同）
-    4. 选择模型、宽高比、分辨率（视频类还有时长，受 API/参考图约束）
-    5. 输出图片/视频的空位
-- 在生成过程中，可以有某种计时器显示运行时间，不要让用户感觉卡住了
 
-# 其他要求
-- Gemini api key是launch网站之���由用户设置的环境变量，千万不能泄露或者hard-code在代码里
-- 所有代码是英文，但是网站上的文字（例如介绍）和提示词可以用中文
-- 网站页面风格：请用比较美观的模板和风格，不用太花哨，但是要有艺术气息
+- 启动页：密码登录（密码来自环境变量）。
+- 登录后侧栏进入各功能，每项含：简介、**必填**提示词、上传区（A/B 最多三张参考图，均可空；C 起始帧必填、结尾可选、可勾选与起始相同）、模型/宽高比/分辨率（视频含时长，受 API/参考图约束）、结果展示区。
+- 生成中显示耗时，避免「卡住」感。
 
+# 其他
 
-# 进一步要求/修改建议
-- 无论我在哪个机器launch这个server，我希望url不要变（debug阶段可以用localhost或者x.x.x.x，但最终开放的版本肯定不行），可以是我自己设计的一个url，但是我希望如果我更换serve的机器这个url不会改变，这样用户能一直用相同url访问。我不确定这个能不能做到，请你给出方案。
+- `GEMINI_API_KEY` 仅环境变量，禁止写入代码仓库。
+- 代码英文；界面文案与提示词可用中文。
+- 视觉：简洁、有一定设计感。
 
-- 对于上述模型名称、分辨率、宽高比的选项，我希望不是hard-code的list，而是能够有一个独立让我修改的地方，因为这些api支持的选项可能随时变化。
+# 稳定 URL 与可配置选项
 
-**实现说明（Web UI）**：选项列表集中在 `web/config/generation_options.json`（可用环境变量 `GENERATION_OPTIONS_PATH` 指向其他文件）。图片模型、视频/视频生成（首尾过渡）的 Veo 模型名、宽高比、分辨率、时长等均从此处加载；修改后一般无需重编前端，但若改 React/样式需 `cd web/frontend && npm run build` 更新 `web/backend/static/`。
+- 稳定访问域名：用自有域名 + DNS、静态 IP、反代或隧道等（见 WEB_DEV_GUIDE §8）。
+- 模型名、分辨率、宽高比等：**不要写死在代码里**；集中在 **`web/config/generation_options.json`**，可用 **`GENERATION_OPTIONS_PATH`** 指向其他文件。改 JSON 通常不必重编前端；改 React/样式需 `cd web/frontend && npm run build`。

docs/WEB_DEV_GUIDE.md

@@ -1,20 +1,18 @@
 # Web UI — developer guide
 
-How to **set up, run, configure, and deploy** the Gemini Studio Web stack (FastAPI + React). End users only need the public URL and password.
+Set up, run, and deploy the Gemini Studio Web stack (FastAPI + React). Product scope: **[SPEC_WEB_UI.md](./SPEC_WEB_UI.md)**.
 
-For **what to build** (features, UX intent, examples page scope), see **[`SPEC_WEB_UI.md`](./SPEC_WEB_UI.md)**.
-
-**Layout:** Application code lives under **`VideoGeneration-release/web/`**. All `from web.backend...` imports assume **`PYTHONPATH`** includes **`VideoGeneration-release`** (the parent of the `web/` directory). Do not set `PYTHONPATH` to `web/` itself—that will break imports.
+**Imports:** Code lives under `VideoGeneration-release/web/`. Use **`PYTHONPATH=.`** with cwd = **`VideoGeneration-release`** (parent of `web/`). Do not set `PYTHONPATH` to `web/` alone.
 
 ## 1. Prerequisites
 
-- **Python** 3.10+ recommended.
-- **Node.js** 18+ and **npm** (for building the frontend).
-- **ffmpeg** on your `PATH` (same as the CLI video scripts; used to strip audio from MP4s).
+- Python 3.10+
+- Node.js 18+ and npm (frontend build)
+- **ffmpeg** on `PATH` (strip audio from MP4s)
 
-## 2. Python virtual environment
+## 2. Python venv
 
-From **`VideoGeneration-release`** (the directory that contains `web/`):
+From **`VideoGeneration-release`**:
 
 ```bash
 cd /path/to/VideoGeneration-release
@@ -25,16 +23,14 @@ pip install -r web/requirements.txt
 
 ## 3. Environment variables
 
-Set these before starting Uvicorn (or put them in a `.env` file and load with your process manager—**do not** commit real secrets):
+Do not commit secrets; use a `.env` with your process manager if you like.
 
 | Variable | Purpose |
 |----------|---------|
-| `GEMINI_API_KEY` | Gemini API key (server only; never exposed to the browser). |
-| `WEB_UI_PASSWORD` | Login password for the web UI. |
-| `SESSION_SECRET` | Random string for signing session cookies, e.g. `openssl rand -hex 32`. |
-| `GENERATION_OPTIONS_PATH` | Optional. Absolute path to a JSON file that overrides the default option lists. If unset, the server uses `web/config/generation_options.json`. |
-
-Example for local debugging:
+| `GEMINI_API_KEY` | Server-side only. |
+| `WEB_UI_PASSWORD` | Login password. |
+| `SESSION_SECRET` | Session signing, e.g. `openssl rand -hex 32`. |
+| `GENERATION_OPTIONS_PATH` | Optional. Overrides default `web/config/generation_options.json`. |
 
 ```bash
 export GEMINI_API_KEY="your_key"
@@ -42,16 +38,14 @@ export WEB_UI_PASSWORD="password"
 export SESSION_SECRET="$(openssl rand -hex 32)"
 ```
 
-## 4. Configurable model / resolution / aspect lists
+## 4. `generation_options.json`
 
-Edit **`web/config/generation_options.json`** (or the file pointed to by `GENERATION_OPTIONS_PATH`). The UI loads these values from **`GET /api/config/generation-options`** after login—no frontend rebuild is required when you change only this JSON. Rebuild the frontend only when you change React/TS/CSS.
+Edit **`web/config/generation_options.json`** (or the file from `GENERATION_OPTIONS_PATH`). The UI loads **`GET /api/config/generation-options`** after login. JSON-only changes need no frontend rebuild; React/TS/CSS changes do.
 
-Schema (informal):
+- **`image`**: `models` (`value` + `label`), `aspect_ratios`, `resolutions`, `thinking_levels`.
+- **`video`** / **`video_frames`**: `models`, `aspect_ratios`, `resolutions`, `durations_seconds`. On **`video`**, **`supports_reference_images`** (e.g. Veo Lite = `false`). With reference images, duration is forced to **8s**. **首尾帧** route always **8s** (no 4/6s like prompt-only 720p).
 
-- **`image`**: `models` (`value` + `label`; e.g. **（快速）** for Flash vs **（标准）** for Pro), `aspect_ratios`, `resolutions`, `thinking_levels` (`value` + `label`).
-- **`video`** / **`video_frames`**: `models` (`value` + `label`, Veo IDs), `aspect_ratios`, `resolutions`, `durations_seconds`. On **`video`**, each model may set **`supports_reference_images`** (boolean); e.g. Veo 3.1 Lite is **`false`**. With reference images, the backend also forces **8s** duration per API rules. The **首尾帧** API route always uses **8s** (frame-conditioned video does not accept 4/6s like prompt-only 720p).
-
-## 5. Build the frontend once
+## 5. Build frontend
 
 ```bash
 cd web/frontend
@@ -59,96 +53,109 @@ npm install
 npm run build
 ```
 
-Output goes to **`web/backend/static/`**. If this directory is missing, the API still runs, but visiting the root URL returns 503 until you build.
-
-## 6. Launch the server
+Output: **`web/backend/static/`**. Missing build → root URL returns 503.
 
-From **`VideoGeneration-release`** (parent of `web/`):
+## 6. Run server
 
 ```bash
 cd /path/to/VideoGeneration-release
 PYTHONPATH=. uvicorn web.backend.main:app --host 127.0.0.1 --port 8000
 ```
 
-For LAN testing from other devices on the same network:
+LAN: `--host 0.0.0.0`. Dev: add `--reload`.
+
+## 7. Dev mode (hot reload)
+
+**A** — API, cwd **`VideoGeneration-release`**:
 
 ```bash
-cd /path/to/VideoGeneration-release
-PYTHONPATH=. uvicorn web.backend.main:app --host 0.0.0.0 --port 8000
+PYTHONPATH=. uvicorn web.backend.main:app --reload --host 127.0.0.1 --port 8000
 ```
 
-Use `--reload` during development.
+**B** — Vite (`web/frontend`): `npm run dev` (proxies `/api` to 8000). Open the printed URL (e.g. `http://127.0.0.1:5173`).
 
-## 7. Development mode (hot reload)
+## 8. Stable URL
 
-**Terminal A** — API (cwd = **`VideoGeneration-release`**):
+The app does not provide a hostname. Use DNS to a domain you control, static/elastic IP, reverse proxy (nginx/Caddy), or a tunnel (Cloudflare Tunnel, Tailscale Funnel, etc.). **One DNS name → current server** when you move machines.
 
-```bash
-cd /path/to/VideoGeneration-release
-PYTHONPATH=. uvicorn web.backend.main:app --reload --host 127.0.0.1 --port 8000
-```
+## 9. Checklist
 
-**Terminal B** — Vite (proxies `/api` to port 8000):
+- [ ] `ffmpeg -version`
+- [ ] `pip install -r web/requirements.txt`
+- [ ] `npm run build` in `web/frontend` at least once
+- [ ] `GEMINI_API_KEY`, `WEB_UI_PASSWORD`, `SESSION_SECRET` set
+- [ ] Uvicorn from **`VideoGeneration-release`** with `PYTHONPATH=.`
 
-```bash
-cd /path/to/VideoGeneration-release/web/frontend && npm run dev
-```
+## 10. Hugging Face Spaces (Docker)
 
-Open the URL Vite prints (e.g. `http://127.0.0.1:5173`). The API key stays on the server; the browser only talks to Vite, which forwards `/api` to Uvicorn.
+Use **Docker** (`sdk: docker`), not Streamlit/Gradio. **`Dockerfile`** at repo root next to `web/` and `assets/`.
 
-## 8. Stable URL when you change machines
+### 10.1 Create Space
 
-The application does **not** assign a public hostname by itself. A stable URL for users is an **infrastructure** concern:
+[Hugging Face](https://huggingface.co/) → New Space → **SDK: Docker**. Space id: **`YOUR_USERNAME/YOUR_SPACE_NAME`**.
 
-1. **Own domain + DNS**  
-   Register a domain (e.g. `studio.example.com`). Create an **A** (or **AAAA**) record pointing to the **current** server’s public IP. When you move to a new machine, update the DNS record to the new IP. Users keep the same hostname.
+### 10.2 Root `README.md`
 
-2. **Static IP or elastic IP**  
-   If your cloud provider offers a static/elastic IP, attach it to whichever instance runs the app; point your DNS name to that IP.
+YAML frontmatter must validate. This repo’s README is preconfigured.
 
-3. **Reverse proxy**  
-   Run **nginx** or **Caddy** on the server (or a small VPS in front): TLS termination, `proxy_pass` to `127.0.0.1:8000`. Users hit `https://studio.example.com` only.
+- **`sdk: docker`**
+- **`colorFrom`** / **`colorTo`**: each must be one of **`red`**, **`yellow`**, **`green`**, **`blue`**, **`indigo`**, **`purple`**, **`pink`**, **`gray`** (other names → upload error).
 
-4. **Tunnel / no public IP**  
-   **Cloudflare Tunnel**, **Tailscale Funnel**, or similar gives you a stable hostname without opening ports on your home router; the tunnel endpoint can be repointed when the backend machine changes (depending on the product).
+### 10.3 Upload
 
-5. **What not to expect**  
-   Hard-coding `localhost` or a raw IP in the app will not give a stable branded URL. The fix is always: **one DNS name you control** → **current server location**.
+**Cwd:** **`VideoGeneration-release`** (contains `Dockerfile`, `web/`, `assets/`).
 
-## 9. Quick checklist
+**CLI** ([write token](https://huggingface.co/settings/tokens)):
 
-- [ ] `ffmpeg` works: `ffmpeg -version`
-- [ ] `pip install -r web/requirements.txt` in a venv
-- [ ] `npm run build` in `VideoGeneration-release/web/frontend` at least once
-- [ ] Three env vars set: `GEMINI_API_KEY`, `WEB_UI_PASSWORD`, `SESSION_SECRET`
-- [ ] Start Uvicorn with `PYTHONPATH=.` from **`VideoGeneration-release`** (folder that contains `web/`)
+```bash
+pip install -U huggingface_hub
+huggingface-cli login
+cd /path/to/VideoGeneration-release
+hf upload YOUR_USERNAME/YOUR_SPACE_NAME . . --repo-type space
+```
 
-## 10. Hugging Face Spaces (Docker)
+Example:
+
+```bash
+hf upload LehongWu/VideoGeneration-release . . --repo-type space
+```
+
+Then check **Space → Logs** for the Docker build.
 
-This UI is **not** Streamlit/Gradio; deploy with **`sdk: docker`** and the **`Dockerfile`** at the repo root (same directory as `web/` and `assets/`).
+**Git:**
 
-1. Create a **Docker** Space and point it at this repository (or push this folder to a GitHub repo and connect the Space).
-2. In the Space **Settings → Variables and secrets**, add **Repository secrets** (or Variables) with exactly these names:
+```bash
+git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+git push -u hf main
+```
 
-   | Name | Purpose |
-   |------|---------|
-   | `GEMINI_API_KEY` | Same as local; never commit it. |
-   | `WEB_UI_PASSWORD` | Password users type on the login page. |
-   | `SESSION_SECRET` | Same as local, e.g. `openssl rand -hex 32`. |
+Or connect GitHub in Space settings and push there.
 
-   Hugging Face injects them as environment variables; the app reads them the same way as on your laptop.
+### 10.4 Secrets
 
-3. The container listens on **`PORT`** if set (Spaces often set it); otherwise **`7860`**. Do not hard-code a port in the app; the provided `Dockerfile` uses `uvicorn ... --port ${PORT:-7860}`.
+**Settings → Variables and secrets** — names must match exactly (case-sensitive). Same as [§3](#3-environment-variables).
 
-4. **ffmpeg** is installed in the image (required for stripping audio from generated MP4s).
+| Name | Purpose |
+|------|---------|
+| `GEMINI_API_KEY` | Gemini key; never commit. |
+| `WEB_UI_PASSWORD` | Login password. |
+| `SESSION_SECRET` | e.g. `openssl rand -hex 32`. |
 
-5. Optional: set **`GENERATION_OPTIONS_PATH`** in the same secrets UI if you mount a custom JSON elsewhere; otherwise the bundled `web/config/generation_options.json` is used.
+Optional: `GENERATION_OPTIONS_PATH` (custom JSON path inside the container).
 
-6. Build can take several minutes on HF; first request after idle may hit cold start.
+Saving restarts the Space. Never put secrets in Git or `README.md`.
 
-Local test of the image (from **`VideoGeneration-release`**):
+### 10.5 Runtime
+
+- Listens on **`PORT`** or **`7860`** (`Dockerfile`: `uvicorn ... --port ${PORT:-7860}`).
+- **`--forwarded-allow-ips='*'`** — required behind HF’s reverse proxy so `X-Forwarded-Proto: https` is trusted. Without it, Uvicorn often sees `http`, session cookies misbehave, and the UI **keeps asking you to log in**.
+- **ffmpeg** in image.
+- First build / cold start can take minutes.
+
+### 10.6 Local Docker
 
 ```bash
+cd /path/to/VideoGeneration-release
 docker build -t gemini-studio-web .
 docker run --rm -p 7860:7860 \
   -e GEMINI_API_KEY="your_key" \
@@ -157,4 +164,4 @@ docker run --rm -p 7860:7860 \
   gemini-studio-web
 ```
 
-Then open `http://127.0.0.1:7860`.
+Open `http://127.0.0.1:7860`.