| # Web UI — developer guide |
|
|
| Setup, run, deploy (FastAPI + React). Product scope: **[SPEC_WEB_UI.md](./SPEC_WEB_UI.md)**. |
|
|
| **Imports:** Code under `VideoGeneration-release/web/`. Run Python with cwd **`VideoGeneration-release`** and **`PYTHONPATH=.`** (not `web/` alone). |
|
|
| ## Prerequisites |
|
|
| Python 3.10+, Node 18+, npm, **ffmpeg** on `PATH`. |
|
|
| ## Python venv |
|
|
| ```bash |
| cd /path/to/VideoGeneration-release |
| python3 -m venv .venv |
| source .venv/bin/activate # Windows: .venv\Scripts\activate |
| pip install -r web/requirements.txt |
| ``` |
|
|
| ## Environment variables |
|
|
| Do not commit secrets. |
|
|
| | Variable | Purpose | |
| |----------|---------| |
| | `GEMINI_API_KEY` | Server-side API key. | |
| | `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`. | |
| | `SESSION_COOKIE_SECURE` | Optional. `1`/`true`/`yes` for HTTPS-only cookies (e.g. Hugging Face). Unset for local `http://127.0.0.1`. Proxy must send `X-Forwarded-Proto` (see Hugging Face / Docker below). | |
|
|
| ```bash |
| export GEMINI_API_KEY="your_key" |
| export WEB_UI_PASSWORD="password" |
| export SESSION_SECRET="$(openssl rand -hex 32)" |
| ``` |
|
|
| ## `generation_options.json` |
| |
| Edit **`web/config/generation_options.json`** (or path from `GENERATION_OPTIONS_PATH`). UI loads it via **`GET /api/config/generation-options`** after login. JSON-only changes need no frontend rebuild. |
| |
| - **`image`**: `models`, `aspect_ratios`, `resolutions`. |
| - **`video`** / **`video_frames`**: `models`, `aspect_ratios`, `resolutions`, `durations_seconds`. On **`video`**, **`supports_reference_images: false`** disables reference images for that model (e.g. Veo 3 / Veo 3 Fast — prompt-only; Veo 3.1 Lite — also no reference images). With reference images, duration is **8s**. **首尾帧** route is always **8s**. On **`video_frames`**, **`supports_end_frame: false`** (e.g. Veo 3 / Veo 3 Fast) means only the start frame is used; end-frame UI and last-frame conditioning are omitted. |
|
|
| ## Build frontend |
|
|
| ```bash |
| cd web/frontend |
| npm install |
| npm run build |
| ``` |
|
|
| Output: **`web/backend/static/`**. Without it, root URL returns 503. |
|
|
| ## Run server |
|
|
| ```bash |
| cd /path/to/VideoGeneration-release |
| PYTHONPATH=. uvicorn web.backend.main:app --host 127.0.0.1 --port 8000 |
| ``` |
|
|
| LAN: `--host 0.0.0.0`. Dev: `--reload`. |
|
|
| ## Dev (hot reload) |
|
|
| **API:** `PYTHONPATH=. uvicorn web.backend.main:app --reload --host 127.0.0.1 --port 8000` from repo root. |
|
|
| **Vite:** `cd web/frontend && npm run dev` — proxies `/api` to 8000; open the printed URL (e.g. `http://127.0.0.1:5173`). |
|
|
| ## Stable URL |
|
|
| Use your own DNS/domain, static IP, reverse proxy, or tunnel — no hostname is baked into the app. |
|
|
| ## Checklist |
|
|
| - [ ] `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 repo root with `PYTHONPATH=.` |
|
|
| ## Hugging Face Spaces (Docker) |
|
|
| Use **Docker** Space (`sdk: docker`). **`Dockerfile`** at repo root beside `web/` and `assets/`. |
|
|
| ### Create & upload |
|
|
| [Hugging Face](https://huggingface.co/) → New Space → **SDK: Docker**. Root **`README.md`** YAML must validate (`sdk: docker`; **`colorFrom`** / **`colorTo`** each one of: `red`, `yellow`, `green`, `blue`, `indigo`, `purple`, `pink`, `gray`). |
|
|
| **Upload** from **`VideoGeneration-release`** (contains `Dockerfile`, `web/`, `assets/`): |
|
|
| ```bash |
| pip install -U huggingface_hub |
| huggingface-cli login |
| cd /path/to/VideoGeneration-release |
| hf upload YOUR_USERNAME/YOUR_SPACE_NAME . . --repo-type space |
| ``` |
|
|
| Or add git remote `https://huggingface.co/spaces/USER/SPACE` and push. |
|
|
| ### Secrets |
|
|
| **Settings → Variables and secrets** — same names as the env table above (case-sensitive). Optional: `GENERATION_OPTIONS_PATH`. Saving restarts the Space. |
|
|
| ### Runtime (Dockerfile) |
|
|
| Listens on **`PORT`** or **7860**. **`--forwarded-allow-ips='*'`** is required behind HF’s proxy so HTTPS and session cookies work. **ffmpeg** in image. Cold start can take minutes. |
|
|
| ### 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" \ |
| -e WEB_UI_PASSWORD="your_password" \ |
| -e SESSION_SECRET="$(openssl rand -hex 32)" \ |
| gemini-studio-web |
| ``` |
|
|
| Open `http://127.0.0.1:7860`. |
|
|
