docs/WEB_DEV_GUIDE.md

Web UI — developer guide

Setup, run, deploy (FastAPI + React). Product scope: 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

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).

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

cd web/frontend
npm install
npm run build

Output: web/backend/static/. Without it, root URL returns 503.

Run server

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 → 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/):

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

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.