video-gen

video-gen

Video generation and multi-scene production via fal.ai. Two modes: light (fire-and-forget) and project (interactive pipeline with gates).

Scripts: ./scripts/generate.py, ./scripts/preview.py, ./scripts/project_init.py, ./scripts/project_state.py, ./scripts/decompose.py, ./scripts/keyframe.py, ./scripts/clip.py, ./scripts/assemble.py, ./scripts/character_sheet.py Output dir: ./output/

Setup

export FAL_KEY="your-fal-ai-key"

• Claude Code: copy this skill folder into .claude/skills/video-gen/
• Codex CLI: append this SKILL.md content to your project's root AGENTS.md

For the full installation walkthrough (prerequisites, API keys, verification, troubleshooting), see [references/installation-guide.md](references/installation-guide.md).

Credential management

Three tiers for managing the FAL_KEY environment variable:

1. Vault skill (recommended): If you have a vault or secret-management skill, store the key there and export it before running scripts. Example: export FAL_KEY=$(vault get FAL_KEY)
2. Custom secret manager: Use your team's preferred secret manager (1Password CLI, AWS Secrets Manager, etc.)
3. Plain export: export FAL_KEY='your-fal-ai-key' in your shell profile

For project mode (keyframes + character sheets): also need image-gen peer skill.

Staying Updated

This skill ships with an UPDATES.md changelog and UPDATE-GUIDE.md for your AI agent.

After installing, tell your agent: "Check UPDATES.md in the video-gen skill for any new features or changes."

When updating, tell your agent: "Read UPDATE-GUIDE.md and apply the latest changes from UPDATES.md."

Follow UPDATE-GUIDE.md so customized local files are diffed before any overwrite.

Decision Tree

Need video?
├── Quick one-off clip? ─────────── Light Mode (generate.py)
│   Single prompt, single output, no state
│
└── Multi-scene story/production? ── Project Mode
    ├── New project? ─────────────── project_init.py → G0
    ├── Existing project? ────────── project_state.py --status
    └── Resume at gate? ──────────── Check state, pick up where left off

Quick Reference

Light Mode

# Generate with default model (ltx-2.3)
python ./scripts/generate.py \
  --prompt "A red fox running through snow" \
  --output ./output/

# Generate with specific model and settings
python ./scripts/generate.py \
  --prompt "Tokyo skyline at sunset with dramatic clouds" \
  --model kling-v3 \
  --mode t2v \
  --duration 10 \
  --resolution 1080p \
  --aspect 16:9

# Image-to-video generation
python ./scripts/generate.py \
  --prompt "The character starts walking forward" \
  --mode i2v \
  --image ./path/to/keyframe.png \
  --model veo-3

# Quick preview (uses LTX fast, cheapest)
python ./scripts/preview.py \
  --prompt "Test scene" \
  --mode t2v

Project Mode

# Initialize new project
python ./scripts/project_init.py \
  --name noir-detective \
  --scenes 5 \
  --output-dir ./projects \
  --style "cinematic, moody, film noir" \
  --tier standard \
  --logline "A detective investigates in a cyberpunk city"

# Check project status
python ./scripts/project_state.py --project ./projects/noir-detective

# Generate keyframe for scene
python ./scripts/keyframe.py \
  --project ./projects/noir-detective \
  --scene 1 \
  --style-keywords "cinematic, moody"

# Generate video clip for scene
python ./scripts/clip.py \
  --project ./projects/noir-detective \
  --scene 1 \
  --model kling-v3 \
  --duration 8

# Assemble final video
python ./scripts/assemble.py \
  --clips-dir ./projects/noir-detective/scenes \
  --output ./projects/noir-detective/output/final.mp4

Light Mode

Model Selection

What do you need?
├── Fast drafts + budget? ──────────── ltx-2.3 (fast) $0.04/s
├── Cinematic quality? ─────────────── kling-v3 $0.168/s
├── Dialogue/lip sync? ─────────────── veo-3 $0.20-0.40/s
├── Long clips (>10s)? ─────────────── sora-2 (up to 25s)
├── Budget with audio? ─────────────── wan $0.05-0.10/s
├── Anime/stylized? ────────────────── hailuo $0.045-0.08/s
└── Physics accuracy? ──────────────── cosmos $0.20/video

| Use Case | Model | Cost/5s | Why | |----------|-------|---------|-----| | Fast drafts | ltx-2.3 | $0.20 | Open source, 4K capable, fastest iteration | | Cinematic | kling-v3 | $0.84 | Multi-shot narratives, character consistency | | Dialogue/lip sync | veo-3 | $2.00 | Best-in-class audio sync, natural performances | | Long clips | sora-2 | $2.50 | Up to 25s duration, complex scenes | | Budget with audio | wan | $0.50 | Cheapest audio option, social media | | Anime/stylized | hailuo | $0.40 | Anime support, micro-expressions | | Physics | cosmos | $0.20 | RL-trained on physics, simulation-accurate |

Script Reference: generate.py

| Flag | Default | Description | |------|---------|-------------| | --model | ltx-2.3 | Model alias: ltx-2.3, kling-v3, veo-3, sora-2, wan, hailuo, cosmos, pixverse, grok | | --mode | t2v | t2v (text-to-video) or i2v (image-to-video) | | --prompt | required | Video description | | --image | none | Source image path or URL (required for i2v) | | --duration | 8 | Duration in seconds | | --resolution | 1080p | 720p, 1080p, 1440p, 4k | | --aspect | 16:9 | 16:9, 9:16, 1:1 | | --fps | 24 | Frames per second | | --seed | none | Reproducibility seed | | --output | ./output/ | Output directory or file path | | --no-preview | false | Skip macOS QuickLook preview | | --no-audio | false | Disable audio generation | | --quality | standard | fast, standard, pro | | --dry-run | false | Cost estimate only, no API call | | --timeout | 300 | Queue timeout in seconds | | --negative-prompt | none | What to exclude from generation | | --json | false | Output JSON only (suppress stderr logs) |

Script Reference: preview.py

# Preview existing video file
python ./scripts/preview.py /path/to/video.mp4

# Generate and preview (uses LTX fast, $0.04/s)
python ./scripts/preview.py \
  --prompt "Quick test scene" \
  --mode t2v \
  [--image path] \
  [--output path]

Output JSON Contract

{
  "success": true,
  "file": "/abs/path/to/20260308-143052-t2v-red-fox-snow.mp4",
  "model": "ltx-2.3",
  "mode": "t2v",
  "duration_sec": 8,
  "resolution": "1080p",
  "cost_usd": 0.32,
  "seed": 42,
  "fal_request_id": "abc123"
}

Duration Constraints

| Model | Valid Durations | Notes | |-------|----------------|-------| | LTX-2.3 | 2, 4, 6, 8, 10s | Fixed increments only | | Kling V3/2.6 | 5, 10s | Two options only | | Veo 3.1 | 5-8s | Any value in range | | Sora 2 | 5-20s (std), 5-25s (pro) | Any value in range | | Hailuo | 4-6s | Any value in range | | Wan | 3-5s | Any value in range | | Cosmos | 5-9s | Any value in range |

Cost Quick Reference

| Model | Video Only | With Audio | 4K Available | |-------|-----------|-----------|-------------| | ltx-2.3 (fast) | $0.04/s | $0.04/s | Yes ($0.16/s) | | ltx-2.3 (std) | $0.06/s | $0.06/s | Yes ($0.24/s) | | wan | $0.05/s | $0.10/s | No | | hailuo | $0.045/s | N/A | No | | kling-v3 | $0.168/s | $0.336/s | No | | veo-3 (fast) | $0.10/s | $0.15/s | No | | veo-3 (std) | $0.20/s | $0.40/s | No | | sora-2 (720p) | $0.30/s | included | No | | sora-2 (1080p) | $0.50/s | included | No |

Project Mode

Gate Pipeline (G0-G5)

| Gate | Stage | What | Scripts | JSON Output | |------|-------|------|---------|-------------| | G0 | Project Setup | Initialize project structure, manifest, state | project_init.py | project_dir, manifest, state paths | | G1 | Shot Prompts | Story decomposition into scene prompts | decompose.py | LLM prompt for story breakdown | | G2 | Reference Images | Generate keyframe images per scene | keyframe.py | keyframe image paths, costs | | G3 | Sequence Review | Review and lock shot sequence | `project_state.py --lock-