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
command -v uvmust succeed. If not, tell the user to install uv:curl -LsSf https://astral.sh/uv/install.sh | shRUNWAYML_API_SECRETmust 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-urlfetch arbitrary remote media via the Runway API. Prefer local file paths (uploaded asrunway://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 | Best For | Input | Cost |
|---|---|---|---|
seedance2 | Reference image and video, long duration (up to 15s) | Text, Image, and/or Video | 36 credits/sec |
gen4.5 | High quality, general purpose | Text and/or Image | 12 credits/sec |
gen4_turbo | Fast, image-driven | Image required | 5 credits/sec |
gen4_aleph | Video editing/transformation | Video + Text/Image | 15 credits/sec |
veo3 | Premium quality | Text/Image | 40 credits/sec |
veo3.1 | High quality Google model | Text/Image | 20-40 credits/sec |
veo3.1_fast | Fast Google model | Text/Image | 10-15 credits/sec |
Model Selection Guidance
Map user requests:
- "product ad", "e-commerce", "long video" ->
seedance2 - "fast", "cheap", "quick" ->
veo3.1_fastorgen4_turbo(if they have an image) - "high quality", "best", "cinematic" ->
gen4.5orveo3 - "edit video", "transform video" ->
gen4_alephorseedance2 - No preference ->
seedance2
Parameters
| Param | Description | Default |
|---|---|---|
--prompt | Text description (required) | -- |
--filename | Output filename (required) | -- |
--model | Video model | gen4.5 |
--ratio | Aspect ratio (pixel-based). Common: 1280:720, 720:1280, 960:960. seedance2 also supports 1112:834, 834:1112, 1470:630, etc. | 1280:720 |
--duration | Duration in seconds (model-dependent, seedance2 supports up to 15s) | 5 |
--image-url | Image URL or local file for image-to-video | -- |
--video-url | Video URL or local file for video-to-video (gen4_aleph, seedance2) | -- |
--output-dir | Output directory | cwd |
API credentials come fromRUNWAYML_API_SECRETonly — no--api-keyflag, 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:720Image-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:1280Video-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 seedance2Fast draft:
uv run scripts/generate_video.py --prompt "A cat playing piano" --filename "draft.mp4" --model veo3.1_fast --ratio 1280:720 --duration 4Premium quality:
uv run scripts/generate_video.py --prompt "Cinematic drone shot over Tokyo at night" --filename "tokyo.mp4" --model veo3 --ratio 1280:720 --duration 8Output
- 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-> setRUNWAYML_API_SECRETin the environment (e.g.export RUNWAYML_API_SECRET=...or a.envfile).Error: Task failed -- SAFETY.INPUT.*-> content moderation, suggest different promptError: Task failed -- ASSET.INVALID-> bad input file format, check image/video formatAPI 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.