Veo 3.0 Video Generator

A full-stack web application for generating AI videos using Google's Veo 3.0 model. Generate videos from text prompts or reference images with customizable parameters including video length, aspect ratio, and person generation settings.

Quick Start

# Clone and navigate to project
cd veo3_poc

# Ensure service-account.json is in the root directory

# Run development servers (both frontend and backend)
./run-dev.sh

# Access the application
# Frontend: http://localhost:3000
# Backend API: http://localhost:7394

Architecture

• Frontend: React 18 + Vite + Material-UI 5 + Montserrat typography
• Backend: Flask 3.0 + Google Gen AI SDK 1.17.0
• Authentication: Microsoft Azure AD SSO (MSAL 2.0)
• Storage: Google Cloud Storage for temporary video files
• Deployment: Systemd service + Apache reverse proxy

Features

• Text-to-Video Generation: Create videos from descriptive text prompts
• Image-to-Video Generation: Upload reference images to guide video generation
• Dual Model Support: Choose between Veo 3.0 (high-quality) and Veo 3.0 Fast (optimized for speed)
• Customizable Parameters:
  • Video length (1-60 seconds)
  • Aspect ratio (16:9 landscape or 9:16 portrait)
  • Person generation policy (allow/don't allow)
• Real-time Progress Tracking: Live status updates during video generation
• Automatic File Management: Downloads and cleanup handled automatically
• Usage Tracking: Webhook integration for monitoring generation requests
• Development Mode: Local development with authentication bypass

Prerequisites

• Python 3.13+ (or 3.8+)
• Node.js 16+
• Google Cloud Project with Veo 3.0 API access
• Google Cloud Storage bucket
• Service account JSON key with appropriate permissions
• Microsoft Azure AD application configured (for production SSO)

Setup Instructions

Backend Setup

1. Navigate to the backend directory:

   cd backend
   

2. Create and activate virtual environment:

   python -m venv venv
   source venv/bin/activate  # Linux/Mac
   # or
   venv\Scripts\activate  # Windows
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure environment variables:

   # For development
   cp .env.development .env
   
   # For production
   cp .env.production .env
   # Edit .env with your specific configuration if needed
   

5. Run in development:

   python app.py
   

Frontend Setup

1. Navigate to the frontend directory:

   cd frontend
   

2. Install dependencies:

   npm install
   

3. Configure environment variables:

   # For development
   cp .env.development .env
   
   # For production
   cp .env.production .env
   # Edit .env with your specific configuration if needed
   

4. Run in development:

   npm run dev
   

5. Build for production:

   npm run build
   

Production Deployment

Backend Deployment (systemd service)

1. Copy the backend files to your server
2. Update paths in veo-video-generator.service
3. Copy service file:

   sudo cp veo-video-generator.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable veo-video-generator
   sudo systemctl start veo-video-generator
   

Frontend Deployment

1. Build the frontend:

   cd frontend
   npm run build
   

2. Copy dist/ contents to your web server directory:

   cp -r dist/* /path/to/your/web/server/veo/
   

Apache Configuration

Add the Apache configuration to your virtual host. Update paths as needed.

Required Apache Modules

Ensure these modules are enabled:

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod rewrite
sudo a2enmod headers
sudo a2enmod expires
sudo systemctl restart apache2

Configuration Files

1. Main Apache Config: Use apache.conf for virtual host configuration
2. Frontend .htaccess: Copy apache-htaccess.txt to /path/to/your/web/server/veo/.htaccess

Project Structure

veo3_poc/
├── backend/                    # Flask backend application
│   ├── routes/                # API and health check endpoints
│   │   ├── api.py            # Main API routes (generate, status, download, cleanup)
│   │   └── health.py         # Health check endpoints
│   ├── utils/                 # Utility modules
│   │   ├── auth.py           # Google Cloud authentication
│   │   └── storage.py        # GCS operations and image processing
│   ├── app.py                # Flask app initialization and CORS config
│   ├── config.py             # Configuration management
│   ├── video_generator.py   # Core Veo 3.0 integration logic
│   ├── requirements.txt      # Python dependencies
│   ├── .env.development      # Development environment config
│   ├── .env.production       # Production environment config
│   └── temp_downloads/       # Temporary video storage
├── frontend/                  # React frontend application
│   ├── src/
│   │   ├── components/       # React components
│   │   │   ├── VideoForm.jsx        # Main video generation form
│   │   │   ├── VideoGenerator.jsx   # Top-level container
│   │   │   ├── ProgressIndicator.jsx # Status display
│   │   │   ├── Layout.jsx           # App layout wrapper
│   │   │   ├── AuthGuard.jsx        # Authentication wrapper
│   │   │   └── DevAuthWrapper.jsx   # Dev mode auth bypass
│   │   ├── config/           # MSAL configuration
│   │   ├── services/         # API service layer
│   │   ├── hooks/            # Custom React hooks
│   │   └── App.jsx           # Main app component
│   ├── .env.development      # Development environment config
│   ├── .env.production       # Production environment config
│   └── package.json          # Node.js dependencies
├── service-account.json       # Google Cloud service account key
├── run-dev.sh                # Development startup script
├── apache.conf               # Apache virtual host configuration
├── apache-htaccess.txt       # Frontend .htaccess rules
└── veo-video-generator.service # Systemd service definition

Configuration

Environment File Structure

The application uses environment-specific configuration files:

Backend:

• .env.development - Debug mode, localhost CORS, development settings
• .env.production - Production mode, strict CORS, optimized for deployment
• .env - Active environment file (copy from development or production)

Frontend:

• .env.development - Localhost API, authentication bypass (VITE_DEV_MODE=true)
• .env.production - Production API, MSAL authentication enabled (VITE_DEV_MODE=false)
• .env - Active environment file (copy from development or production)

Backend Environment Variables

Variable	Description	Default/Example
PROJECT_ID	Google Cloud project ID	optical-414516
REGION	Google Cloud region	us-central1
MODEL_ID	Veo model identifier	veo-3.0-generate-preview
MODEL_FAST_ID	Veo Fast model identifier	veo-3.0-fast-generate-preview
OUTPUT_GCS_BUCKET_NAME	GCS bucket for temporary storage	optical-veo3-test
SERVICE_ACCOUNT_KEY_PATH	Path to service account JSON	../service-account.json
PORT	Backend server port	7394
FLASK_ENV	Environment mode	development or production
FLASK_DEBUG	Debug mode	True or False
FRONTEND_URL	Frontend URL for CORS	http://localhost:3000 or production URL
WEBHOOK_URL	Usage tracking webhook URL	Optional
WEBHOOK_ENABLED	Enable usage tracking	true or false

Frontend Environment Variables

Variable	Description	Example
VITE_API_BASE_URL	Backend API URL	http://localhost:7394
VITE_APP_TITLE	Application title	Veo Video Generator (Dev)
VITE_DEV_MODE	Development mode flag	true or false
VITE_MSAL_CLIENT_ID	Azure AD client ID	dd434534-...
VITE_MSAL_AUTHORITY	Azure AD authority URL	https://login.microsoftonline.com/...
VITE_MSAL_REDIRECT_URI	Authentication redirect URI	http://localhost:3000

Key Dependencies

Backend

• flask==3.0.0 - Web framework
• flask-cors==4.0.0 - Cross-origin resource sharing
• google-genai==1.17.0 - Google Gen AI SDK for Veo 3.0
• google-cloud-storage==2.12.0 - GCS file operations
• google-cloud-aiplatform==1.38.0 - Vertex AI platform
• hypercorn==0.15.0 - ASGI server for production
• python-dotenv==1.0.0 - Environment configuration
• Pillow==10.1.0 - Image processing

Frontend

• react==18.2.0 - UI framework
• @mui/material==5.15.1 - Material-UI component library
• @azure/msal-react==2.0.7 - Microsoft authentication
• axios==1.6.2 - HTTP client
• vite==5.0.8 - Build tool and dev server
• @fontsource/montserrat==5.0.16 - Typography

API Endpoints

Main API Routes (/api)

Method	Endpoint	Description	Request Body
POST	/api/generate	Start video generation	{ prompt, model_name, video_length_sec, aspect_ratio, person_generation, image }
GET	/api/status/<job_id>	Check generation status	-
GET	/api/download/<job_id>	Download completed video	-
DELETE	/api/cleanup/<job_id>	Manual cleanup of temp files	-

Health Check Routes

Method	Endpoint	Description
GET	/health	Detailed health check with configuration info
GET	/ping	Simple ping response

Video Generation Flow

1. User Input: User provides prompt, optional image, and generation parameters
2. Job Creation: Backend creates unique job ID and initializes status tracking
3. Image Processing (if provided): Image validated, converted to JPEG, uploaded to GCS
4. API Call: Request sent to Google Gen AI SDK with Veo 3.0 model
5. Polling: Backend polls long-running operation every 30 seconds
6. Progress Updates: Frontend fetches status updates every 2 seconds
7. Video Download: Completed video downloaded from GCS to local temp storage
8. User Download: Video served to user and temporary files cleaned up

Security

• CORS configured for specific frontend domain(s)
• Azure AD SSO authentication in production (bypassed in dev mode)
• Automatic cleanup of temporary files after download
• Service account with minimal required GCS permissions
• Secure headers in Apache configuration
• Backend service runs as non-root user in production

Monitoring and Logging

Backend Logs

# View systemd service logs (production)
sudo journalctl -u veo-video-generator -f

# View Flask app logs (development)
# Logs printed to terminal running app.py

Frontend Logs

• Browser console for React errors
• Network tab for API request/response debugging
• Apache access logs: /var/log/apache2/access.log

Usage Tracking

• Webhook integration sends generation requests to configured endpoint
• Tracks: user email, prompt, model, timestamp
• Can be disabled via WEBHOOK_ENABLED=false

Troubleshooting

Common Issues

Issue	Possible Cause	Solution
Authentication fails	Azure AD misconfiguration	Verify VITE_MSAL_CLIENT_ID, VITE_MSAL_AUTHORITY, and redirect URIs match Azure AD app
Backend connection error	Service not running or CORS issue	Check systemctl status veo-video-generator and FRONTEND_URL in backend .env
Video generation fails	Invalid credentials or API access	Verify service account permissions and Veo 3.0 API is enabled in GCP
Image upload rejected	Invalid format or size	Ensure image is <10MB and meets minimum 720x720 resolution
Download hangs	GCS permission issue	Check service account has storage.objects.get permission on bucket
Model not found	Wrong region or model ID	Verify Veo 3.0 is available in specified REGION

Debug Mode

Enable detailed logging in development:

# Backend
FLASK_DEBUG=True in .env

# Frontend
Check browser console with React DevTools

Development

Local Development Setup

For local testing without authentication:

1. Quick Start (runs both backend and frontend):

   ./run-dev.sh
   

2. Manual Start:

   Backend (Terminal 1):

   cd backend
   cp .env.development .env
   python app.py
   

   Frontend (Terminal 2):

   cd frontend
   npm run dev
   

Development Features

• Authentication Bypass: MSAL/SSO automatically bypassed when VITE_DEV_MODE=true
• CORS: Configured for localhost:3000 and 127.0.0.1:3000
• Hot Reload: Vite dev server auto-reloads frontend on file changes
• Debug Mode: Flask runs with detailed error pages and auto-reload
• Mock User: Shows "Dev User" in the interface header

Development URLs

• Backend API: http://localhost:7394
• Frontend: http://localhost:3000
• No authentication required in dev mode

Additional Files

• user_docs.md: Comprehensive user documentation and feature guide
• CLAUDE.md: AI assistant guidance for working with this codebase
• extract_usage_logs.sh: Script for extracting usage data from webhook logs
• veo3.zip: Archive of production deployment artifacts
• .gitignore: Git exclusions (includes .env, node_modules, temp_downloads, etc.)

Notes

• The original veo.py standalone script has been replaced by the full-stack application
• Number of videos per request is hard-coded to 1 (UI option removed)
• Generated videos are automatically cleaned up after download
• Image uploads are automatically converted to JPEG format regardless of input format
• The application uses in-memory job status tracking (consider Redis for production scaling)