README.md

---
title: Product Showcase Studio
emoji: 🎬
colorFrom: gray
colorTo: indigo
sdk: docker
app_port: 7860
---

# Product Showcase Studio

Cinematic product video pipeline: **shot planning** → **KIE Veo / Seedance** → **FFmpeg merge**, with optional **GPT Image** keyframes and **product URL** import.

## Deploy on Hugging Face Spaces

1. **Create a Space** → **Docker** → link this repository (or push these files to a new repo under your account).
2. **Settings → Repository secrets** (or **Variables and secrets**): add at least:
   - **`VITE_API_BASE_URL`** — your Space’s public app URL, same as the address in the browser when the app loads, with no trailing slash (for example `https://YOUR-USERNAME-YOUR-SPACE-NAME.hf.space`). This is required so **callback URLs** and **hosted images** use the correct origin.
   - **`KIE_API_KEY`** — if you use KIE Veo.
   - **`OPENAI_API_KEY`** — optional, for LLM shot plans and GPT Image keyframes.
   - **`REPLICATE_API_TOKEN`** — optional Seedance fallback when KIE is not used.
3. Wait for the build (Node build + Python image). Open the Space URL when the build is **Running**.

The container runs **uvicorn** on **`PORT`** (Spaces set this; default **7860**). **FFmpeg** is installed for the merge step.

### Local Docker (optional)

```bash
docker build -t product-showcase .
docker run --rm -p 7860:7860 \
  -e VITE_API_BASE_URL=http://127.0.0.1:7860 \
  -e KIE_API_KEY=... \
  product-showcase
```

Then open `http://127.0.0.1:7860`.

## Local development

See [FLOW.md](FLOW.md) for architecture and env details.

```bash
# API
cd backend && python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt && python main.py

# UI (separate terminal)
cd frontend && npm install && npm run dev
```

With a built `frontend/dist`, `python main.py` also serves the SPA from the same origin.