Veo Generators - Self-Hosting & Feature Guide

A full-stack, AI-driven application for automated video production using Google's generative models (Gemini, Imagen, Veo). This project acts as an orchestration layer, allowing users to define a creative concept that is automatically broken down into a script, storyboarded, rendered into clips, and stitched together.

---

✨ Features & How-To Guide

The Veo Generators application is structured around a streamlined, pipeline-driven UI. Here is a list of what you can do and how to do it:

1. AI Scriptwriting (Concept to Script)

• What it does: Turns a 1-sentence prompt into a structured, multi-scene video script complete with visual descriptions, narration, and estimated timestamps.
• How to use: From the Dashboard, click New Project. Enter your core concept (e.g., "A cinematic trailer for a sci-fi movie set on Mars"), select your desired video length, and choose an orientation (Landscape/Portrait). The system will automatically draft the scenes for you.

2. Automated Storyboarding

• What it does: Generates static image thumbnails for each scene based on its AI-generated visual description, helping you pre-visualize the video before spending expensive compute on video generation.
• How to use: Once a script is generated, navigate to the project's Storyboard view. You can either auto-generate frames for all scenes at once or click "Generate Frame" on individual scenes to refine them manually.

3. Scene-by-Scene Video Generation (Veo Integration)

• What it does: Renders high-quality short video clips (typically 4-8 seconds) for every scene. It uses the generated storyboard frame and the scene's visual description as a combined text-and-image prompt for Google's Veo models.
• How to use: After finalizing your storyboards, click the Render Scenes or Generate Video button. The backend handles the asynchronous rendering in the background.

4. Final Video Stitching

• What it does: Merges all individually generated scene clips into a single, cohesive MP4 video file.
• How to use: Once all individual scenes are successfully generated by Veo, the backend automatically triggers the Google Cloud Video Transcoder API to assemble the final video. The final MP4 URL will be available in the UI.

5. Cost & Token Tracking

• What it does: Provides an in-UI estimate of API costs and token usage to help you monitor and prevent runaway cloud bills.
• How to use: Check the Cost Breakdown pill visible in the project view. It automatically tallies tokens used for scripting and the estimated cost for image and video generations.

6. Gated Access Control

• What it does: Restricts usage to authorized users via an invite-code system, protecting your expensive AI endpoints from public abuse.
• How to use: Configure the MASTER_INVITE_CODE environment variable on your server. Users must enter a valid invite code to access the app or process projects.

---

🛠 Self-Hosting on Google Cloud Platform (Cloud Run)

This project is fully containerized and designed to run seamlessly on Google Cloud Run. Follow these steps to deploy your own instance.

1. Prerequisites

• A Google Cloud Platform (GCP) Account with an active Project.
• Google Cloud CLI (gcloud) installed and authenticated locally.
• Docker installed locally.
• Node.js (18+) and Python (3.12+) installed for running local pre-deployment checks.

2. Enable Required GCP APIs

Enable the following APIs in your GCP project. You can do this via the GCP Console or using the following CLI command:

gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  firestore.googleapis.com \
  storage.googleapis.com \
  aiplatform.googleapis.com \
  transcoder.googleapis.com

3. Setup GCP Services & Infrastructure

Cloud Storage (GCS)

Create a bucket to store the generated thumbnail images and video MP4s.

gcloud storage buckets create gs://YOUR_GCS_BUCKET_NAME --location=YOUR_REGION

(Note: Ensure the bucket has proper IAM permissions to allow your application to read/write objects).

Firestore Database

Initialize a Firestore database in Native mode within your GCP console. This stores all project metadata, scene data, and application state.

Artifact Registry

Create a Docker repository to host your compiled container images:

gcloud artifacts repositories create superexam-repo \
  --repository-format=docker \
  --location=YOUR_REGION \
  --description="Veo Generators Docker repo"

4. IAM Permissions & Service Account

Cloud Run uses a Service Account to interact with other GCP services. It is highly recommended to create a dedicated Service Account for this application. The service account needs the following IAM roles:

• Cloud Datastore User (roles/datastore.user): To read and write metadata to Firestore.
• Storage Object Admin (roles/storage.objectAdmin): To upload images and videos to your GCS Bucket.
• Vertex AI User (roles/aiplatform.user): To access Gemini, Imagen, and Veo models via Vertex AI.
• Transcoder Admin (roles/transcoder.admin): To submit and manage video stitching jobs to the Transcoder API.

Example CLI command to grant a role:

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:YOUR_SERVICE_ACCOUNT_EMAIL" \
  --role="roles/aiplatform.user"

5. Environment Variables Configuration

Create a .env file in the root directory. You can copy the provided .env.example file. These variables are consumed by the deployment script and injected into your Cloud Run instance.

# Google Cloud Configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=asia-south1
GEMINI_REGION=global
VEO_REGION=us-central1
GCS_BUCKET=your-bucket-name

# AI Model Configuration
OPTIMIZE_PROMPT_MODEL=gemini-3-pro-preview
STORYBOARD_MODEL=gemini-3.1-flash-image-preview
VIDEO_GEN_MODEL=veo-3.1-generate-preview

# Service Configuration
SERVICE_NAME=veo-generators
ARTIFACT_REPO=superexam-repo

# Auth
MASTER_INVITE_CODE=your-secret-invite-code

6. Deployment

The project includes a deploy.sh script that automates pre-deployment checks (TypeScript compilation, Python Ruff linting), Docker image creation, Artifact Registry push, and Cloud Run deployment.

1. Authenticate your gcloud CLI:

   gcloud auth login
   gcloud config set project YOUR_PROJECT_ID

2. Make the deployment scripts executable:

   chmod +x deploy.sh pre-deploy.sh

3. Run the deployment:

   ./deploy.sh

The deploy.sh script will build the multi-stage Dockerfile, push it to your Artifact Registry, and deploy it to Cloud Run. Upon a successful deployment, the script will output the secure Cloud Run URL for your self-hosted Veo Generators instance!