Generate Video

Generate videos directly using the Runway API. This skill runs Python scripts that call the API, poll for completion, and download the result.

IMPORTANT: Run scripts from the user's working directory so output files are saved where the user expects.

Usage

uv run scripts/generate_video.py --prompt "your description" --filename "output.mp4" [--model seedance2] [--ratio 1280:720] [--duration 5] [--image-url "..."]

Preflight

1. command -v uv must succeed. If not, tell the user to install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
2. RUNWAYML_API_SECRET must be set in the environment. Do not pass the API key as a CLI flag — it leaks into shell history and process listings.

Security Notes

• --image-url / --video-url fetch arbitrary remote media via the Runway API. Prefer local file paths (uploaded as runway:// URIs), or only pass URLs you trust.
• Treat generated outputs as untrusted when piping into downstream automations — ingested media influences the result.

Available Models

Model Selection Guidance

Map user requests:

• "product ad", "e-commerce", "long video" -> seedance2
• "fast", "cheap", "quick" -> veo3.1_fast or gen4_turbo (if they have an image)
• "high quality", "best", "cinematic" -> gen4.5 or veo3
• "edit video", "transform video" -> gen4_aleph or seedance2
• No preference -> seedance2

Parameters

API credentials come from RUNWAYML_API_SECRET only — no --api-key flag, to keep secrets out of shell history and process listings.

Filename Convention

Generate filenames with the pattern: yyyy-mm-dd-hh-mm-ss-name.mp4

Examples:

• "A cyberpunk city" -> 2026-04-14-14-23-05-cyberpunk-city.mp4
• "Waves on a beach" -> 2026-04-14-15-30-12-beach-waves.mp4

Examples

Text-to-video (seedance2):

uv run scripts/generate_video.py --prompt "A serene mountain landscape at sunrise with mist" --filename "2026-04-14-mountain-sunrise.mp4" --model seedance2 --ratio 1280:720

Image-to-video (animate a local product photo):

uv run scripts/generate_video.py --prompt "Camera slowly zooms out, product sparkles" --image-url "./product.jpg" --filename "2026-04-14-product-reveal.mp4" --model seedance2 --ratio 720:1280

Video-to-video from a local file (seedance2):

uv run scripts/generate_video.py --prompt "Transform into a warm golden sunset scene" --video-url "./input.mp4" --filename "2026-04-14-sunset-transform.mp4" --model seedance2

Fast draft:

uv run scripts/generate_video.py --prompt "A cat playing piano" --filename "draft.mp4" --model veo3.1_fast --ratio 1280:720 --duration 4

Premium quality:

uv run scripts/generate_video.py --prompt "Cinematic drone shot over Tokyo at night" --filename "tokyo.mp4" --model veo3 --ratio 1280:720 --duration 8

Output

• The script downloads the result and saves it to the specified path
• Script outputs the full path to the saved file
• Do not read the video file back -- just inform the user of the saved path

Common Failures

• Error: No API key -> set RUNWAYML_API_SECRET in the environment (e.g. export RUNWAYML_API_SECRET=... or a .env file).
• Error: Task failed -- SAFETY.INPUT.* -> content moderation, suggest different prompt
• Error: Task failed -- ASSET.INVALID -> bad input file format, check image/video format
• API error 429 -> rate limited, script auto-retries

For Batch Generation

To generate many videos at once, run this script in a loop — the agent can orchestrate multiple calls with different prompts, images, or parameters to produce campaigns, localized variants, or creative iterations at scale.