video-generator

What this skill does

# Video Generator

Generate professional short-form videos using Google VEO 3.1 (with native audio) or OpenAI Sora (high visual quality, up to 12s).

## Prerequisites & Setup

### API Keys

You need at least one. Both gives you maximum flexibility.

**VEO (Google):**
1. Go to [Google AI Studio](https://aistudio.google.com/app/apikey)
2. Sign in with your Google account
3. Click "Create API Key"
4. Copy the generated key

```bash
export GEMINI_API_KEY=your_gemini_key_here
```

**Sora (OpenAI):**
1. Go to [OpenAI Platform](https://platform.openai.com/api-keys)
2. Create a new API key
3. Copy the generated key

```bash
export OPENAI_API_KEY=your_openai_key_here
```

### Install Dependencies

```bash
pip install google-genai requests
```

### Available Models

| Provider | Model | CLI `--model` | Best For |
|----------|-------|---------------|----------|
| **VEO** | Veo 3.1 Standard | `standard` (default) | Quality, audio fidelity, final assets |
| **VEO** | Veo 3.1 Fast | `fast` | Drafts, iteration, quick previews |
| **Sora** | Sora 2 | `sora-2` (default) | Visual quality, creative motion |
| **Sora** | Sora 2 Pro | `sora-2-pro` | Highest Sora quality, slower |

### When to Use Which

| Need | Use |
|------|-----|
| Native synchronized audio (dialogue, SFX) | **VEO** - Sora has no audio |
| Longer clips (12 seconds) | **Sora** - VEO maxes at 8s |
| Higher visual fidelity / artistic styles | **Sora** - stronger on visual aesthetics |
| Fast iteration / drafts | **VEO Fast** - quickest turnaround |
| 4K resolution | **VEO** - Sora uses fixed sizes |
| Negative prompts (exclude elements) | **VEO** - Sora doesn't support them |

### Video Parameters

| Parameter | VEO Options | Sora Options | Default |
|-----------|-------------|--------------|---------|
| **Duration** | 4, 6, or 8 seconds | 4, 8, or 12 seconds | 8s |
| **Resolution** | 720p, 1080p, 4K | Fixed (from aspect ratio) | 720p |
| **Aspect Ratio** | 16:9, 9:16 | 16:9 -> 1280x720, 9:16 -> 720x1280 | 16:9 |
| **Count** | 1-4 variations | 1-4 variations | 1 |
| **Negative Prompt** | Supported | Not supported (ignored) | none |

### Approximate Cost

| Provider | Model | Cost |
|----------|-------|------|
| VEO | Standard | ~$0.025-0.05 per video |
| VEO | Fast | ~$0.01-0.025 per video |
| Sora | sora-2 | ~$0.10 per second of video |
| Sora | sora-2-pro | ~$0.20 per second of video |

### Latency

Video generation is async - expect 11 seconds to 6 minutes depending on server load and provider. The script polls automatically and saves when ready.

---

## Workflow Overview

1. **Define the Concept** - What story does the video tell in 4-12 seconds?
2. **Storyboard the Shot** - Camera, motion, subject, environment
3. **Add Audio Direction** - Dialogue, sound effects, ambient sound (VEO only)
4. **Generate Video** - Run via API
5. **Iterate** - Adjust prompt based on results

## Prompt Rules

1. **150-300 characters is the sweet spot.** Under 100 = generic. Over 400 = the model drops elements unpredictably.
2. **One shot = one action.** Don't pack multiple scene changes or style shifts into one prompt. One camera move + one subject action.
3. **Describe what you want, not what you don't want.** Use the `--negative` flag for exclusions (VEO only), not the main prompt.
4. **Treat audio as a separate layer.** Write audio cues in their own sentences, not mixed into visual descriptions. (VEO only - Sora has no audio.)
5. **Use colon syntax for dialogue.** `A man says: "Hello!"` prevents subtitle artifacts. (VEO only.)
6. **Keep dialogue under 7 words per line.** Longer speech causes lip-sync drift. (VEO only.)
7. **Start simple, then layer.** Begin with a basic prompt, evaluate, then add one variable at a time.
8. **Slow camera movements win.** Fast pans and spins break output. Use tight framing for perceived speed.

---

## Storyboarding the Shot

Structure your prompt with cinematic language. Both VEO and Sora respond well to film terminology:

### Camera Language

| Term | Effect |
|------|--------|
| **Wide shot** | Shows full environment, establishes context |
| **Close-up** | Tight on a subject, emphasizes detail |
| **Tracking shot** | Camera follows subject movement |
| **Dolly in/out** | Camera moves toward or away from subject |
| **Static shot** | Locked camera, subject moves within frame |
| **Slow pan** | Camera rotates horizontally across scene |
| **Overhead / bird's eye** | Looking straight down |
| **Low angle** | Looking up at subject, adds drama |

### Motion Description

Be explicit about what moves and how:

| Don't | Do |
|-------|-----|
| "A dog in a park" | "A golden retriever runs toward camera through tall grass, ears bouncing" |
| "City at night" | "Camera slowly dollies through a neon-lit Tokyo alley as rain puddles reflect signs" |
| "Ocean" | "A single wave forms, curls, and crashes onto wet sand in slow motion" |

### Lighting & Atmosphere

| Term | Mood |
|------|------|
| Golden hour | Warm, nostalgic, cinematic |
| Overcast | Soft, even, contemplative |
| Neon / artificial | Urban, energetic, modern |
| Candlelight | Intimate, quiet |
| Hard shadows | Dramatic, high contrast |

---

## Audio Direction (VEO Only)

VEO 3.1 generates synchronized audio natively. This is a major differentiator.

### Three Types of Audio Cues

**1. Dialogue** - Use colon syntax before quotes:
```
A barista says: "Here you go!" as she slides a latte across the counter.
```
Keep lines under 7 words for clean lip-sync. One sentence max per 8-second clip.

**2. Sound Effects** - Describe specific sounds:
```
The sound of a match striking, then a candle flame flickering to life.
```

**3. Ambient Sound** - Set the sonic environment:
```
Birds chirping in the background, distant traffic hum, morning atmosphere.
```

---

## Prompt Structure (5-Element Priority)

Structure prompts in this order - you don't need all five every time:

1. **Shot Specification** - camera work, framing, movement
2. **Setting & Atmosphere** - location, time, weather, lighting
3. **Subject & Action** - who/what, described in beats
4. **Audio Layer** - dialogue, SFX, ambient (VEO only)
5. **Style/Grade** - artistic treatment, lens, color

```
[Shot type + camera movement]. [Setting and lighting]. [Subject doing action].
[Audio: what you hear]. [Style/grade].
```

### Example Prompts

**Podcast promo (VEO, 16:9):**
```
A close-up tracking shot of a vintage microphone in a warmly lit podcast studio.
Steam rises slowly from a coffee mug beside it. Morning sunlight filters through
blinds, casting soft stripes across the desk. The sound of a quiet room - a clock
ticking, the faint hum of equipment. Cinematic, intimate, inviting.
```

**Social teaser - vertical (Sora, 9:16):**
```
A hand reaches into frame and opens a leather-bound journal on a wooden desk.
The pages flutter briefly before settling on a page covered in handwritten notes.
A pen is set down beside the book. Warm overhead lighting, shallow depth of field.
Shot on 16mm film, natural grain.
```

**Product reveal (either provider, 16:9):**
```
Camera slowly orbits a pair of wireless headphones placed on a dark marble surface.
Dramatic studio lighting with a single warm key light from the left. The headphones
cast a sharp shadow. Premium, minimal, modern.
```

---

## Running the Script

```bash
# VEO: Basic generation (8s, 720p, 16:9)
python scripts/generate_video.py "Your prompt here"

# VEO: Fast draft for iteration
python scripts/generate_video.py "Your prompt here" --model fast

# VEO: High quality vertical video for social
python scripts/generate_video.py "Your prompt" --aspect 9:16 --resolution 1080p

# VEO: Multiple variations to choose from
python scripts/generate_video.py "Your prompt" --count 2 --output ./videos

# VEO: Short clip with specific settings
python scripts/generate_video.py "Your prompt" --duration 4 --resolution 4k --name "hero-clip"

# VEO: Exclude unwanted elements
python scripts/generate_video.py "Your prompt" --negative "text overlays, waterma