runwayml Runway Studio Skills
Generate studio-quality videos, images, and audio using the Runway API. All commands are standalone Python scripts run via uv run from the skill root directory.
Setup
The user must set their Runway API key:
export RUNWAYML_API_SECRET="your-api-key"
All scripts accept --api-key as an alternative.
Commands
All invocations use uv run scripts/<script>.py from the repo root. Dependencies install automatically on first run.
generate_video.py — Video generation
Automatically routes to the correct Runway endpoint based on inputs provided.
# Text to video
uv run scripts/generate_video.py \
--prompt "A product bottle rotating slowly on a marble surface" \
--model seedance2 --ratio 720:1280 --duration 10
# Image to video
uv run scripts/generate_video.py \
--prompt "Smooth camera push-in, soft ambient light" \
--image "https://example.com/product.jpg" \
--model seedance2 --duration 10 --ratio 720:1280
# Image to video from local file
uv run scripts/generate_video.py \
--prompt "Product reveal" \
--image ./product-photo.jpg \
--model gen4_turbo
# Video to video
uv run scripts/generate_video.py \
--video "https://example.com/source.mp4" \
--prompt "Add cinematic color grading" \
--model gen4_aleph --ratio 1280:720
# Character performance
uv run scripts/generate_video.py \
--character ./spokesperson.jpg \
--reference-perf "https://example.com/performance.mp4" \
--ratio 1280:720
Routing logic:
--character+--reference-perf→ character_performance (act_two)--video→ video_to_video--image→ image_to_video- prompt only → text_to_video
Parameters:
| Flag | Description | Default |
|---|---|---|
--prompt |
Text prompt (up to 1000 chars; 3500 for seedance2) | — |
--image |
Image URL or local path | — |
--video |
Video URL or local path | — |
--model |
Model name (see table below) | seedance2 |
--duration |
Duration in seconds | model default |
--ratio |
Resolution ratio (e.g. 1280:720) |
model default |
--audio |
true/false — generate audio |
model default |
--output-count |
Number of outputs, 1-4 (seedance2 only) | 1 |
--seed |
Seed integer for reproducibility | random |
--image-position |
first or last — where the image appears in video |
first |
--references |
Reference image URLs (video-to-video, gen4_aleph) | — |
--character |
Character image/video for act_two | — |
--character-type |
image or video |
image |
--reference-perf |
Performance reference video for act_two | — |
--body-control |
Enable body control (act_two) | off |
--expression-intensity |
1-5 expression intensity (act_two) | 3 |
--output-dir |
Output directory | output |
--filename |
Base name for saved files | video |
--no-poll |
Print task ID without waiting | off |
generate_image.py — Image generation
uv run scripts/generate_image.py \
--prompt "Minimal skincare bottle on white background, studio lighting" \
--model gen4_image --ratio 1080:1080
# With reference images
uv run scripts/generate_image.py \
--prompt "Product in the style of the reference" \
--reference-images "https://example.com/brand-ref.jpg" ./local-ref.png \
--model gen4_image --ratio 1920:1080
Parameters:
| Flag | Description | Default |
|---|---|---|
--prompt |
Text prompt (required) | — |
--model |
gen4_image, gen4_image_turbo, gemini_2.5_flash |
gen4_image |
--ratio |
Resolution ratio | 1080:1080 |
--reference-images |
Up to 3 reference image URLs or local paths | — |
--seed |
Seed integer | random |
--output-dir |
Output directory | output |
--filename |
Base name for saved files | image |
generate_audio.py — Audio generation
Five subcommands mapping to Runway audio endpoints.
# Sound effect
uv run scripts/generate_audio.py sound-effect \
--prompt "Soft whoosh transition sound" --duration 3
# Text to speech
uv run scripts/generate_audio.py tts \
--prompt "Welcome to our product showcase" --voice Leslie
# Speech to speech (voice conversion)
uv run scripts/generate_audio.py speech-to-speech \
--media ./recording.mp3 --media-type audio --voice Noah
# Voice dubbing
uv run scripts/generate_audio.py voice-dub \
--audio "https://example.com/narration.mp3" --target-lang es
# Voice isolation
uv run scripts/generate_audio.py voice-isolate \
--audio ./noisy-recording.mp3
Subcommand parameters:
sound-effect: --prompt (required), --duration (0.5-30s), --loop
tts: --prompt (required), --voice (required, see voice presets below)
speech-to-speech: --media (required), --media-type (audio/video), --voice (required), --remove-noise
voice-dub: --audio (required), --target-lang (required), --disable-cloning, --drop-background, --num-speakers
voice-isolate: --audio (required)
All subcommands also accept: --output-dir, --filename, --no-poll, --api-key
get_task.py — Task management
# Check task status
uv run scripts/get_task.py --task-id "uuid-here"
# Poll until completion
uv run scripts/get_task.py --task-id "uuid-here" --poll
# Poll and download outputs
uv run scripts/get_task.py --task-id "uuid-here" --poll --download
# Cancel/delete a task
uv run scripts/get_task.py --task-id "uuid-here" --delete
Model Selection Guide
Video models
| Model | Best for | Duration | Audio | Key feature |
|---|---|---|---|---|
seedance2 |
Product ads, reference-based video | 4-15s | yes | Reference image support, up to 4 outputs per call, 3500-char prompts |
gen4.5 |
High quality text/image-to-video | 2-10s | no | Best visual quality |
gen4_turbo |
Fast image-to-video | 2-10s | no | Fastest Runway model |
veo3.1 |
Cinematic with audio | 4/6/8s | yes | Built-in contextual audio, up to 1080p |
veo3.1_fast |
Fast cinematic with audio | 4/6/8s | yes | Faster veo3.1 |
veo3 |
Cinematic with audio | 8s | no | Image-to-video with audio |
gen4_aleph |
Video-to-video restyling | — | — | Video input + reference images |
act_two |
Character performance | — | — | Transfer facial/body performance |
For product ads, use seedance2. It supports reference images (product photos fed directly), generates up to 4 variants per call, and produces up to 15s videos.
For cinematic video with audio, use veo3.1. It generates contextual ambient sound automatically.
Image models
| Model | Best for | Key feature |
|---|---|---|
gen4_image |
General image generation | Up to 3 reference images, highest quality |
gen4_image_turbo |
Fast drafts | Requires at least 1 reference image |
gemini_2.5_flash |
Fast image generation | Google Gemini-based |
Audio models
| Model | Endpoint | Purpose |
|---|---|---|
eleven_text_to_sound_v2 |
sound_effect | Sound effects from text description |
eleven_multilingual_v2 |
text_to_speech | TTS with 50 voice presets |
eleven_multilingual_sts_v2 |
speech_to_speech | Voice conversion in audio/video |
eleven_voice_dubbing |
voice_dubbing | Translate + dub to 28 languages |
eleven_voice_isolation |
voice_isolation | Separate voice from background |
Voice presets (TTS and speech-to-speech)
Maya, Arjun, Serene, Bernard, Billy, Mark, Clint, Mabel, Chad, Leslie, Eleanor, Elias, Elliot, Grungle, Brodie, Sandra, Kirk, Kylie, Lara, Lisa, Malachi, Marlene, Martin, Miriam, Monster, Paula, Pip, Rusty, Ragnar, Xylar, Maggie, Jack, Katie, Noah, James, Rina, Ella, Mariah, Frank, Claudia, Niki, Vincent, Kendrick, Myrna, Tom, Wanda, Benjamin, Kiana, Rachel
Supported Ratios
Video ratios by model
gen4.5 / gen4_turbo: 1280:720, 720:1280, 1104:832, 960:960, 832:1104, 1584:672
seedance2: 992:432, 864:496, 752:560, 640:640, 560:752, 496:864, 1470:630, 1280:720, 1112:834, 960:960, 834:1112, 720:1280
veo3.1 / veo3.1_fast / veo3: 1280:720, 720:1280, 1080:1920, 1920:1080
Common ad format ratios
| Platform | Ratio | seedance2 | gen4.5 |
|---|---|---|---|
| TikTok / Reels (9:16) | 720:1280 |
yes | yes |
| YouTube (16:9) | 1280:720 |
yes | yes |
| Instagram Square (1:1) | 960:960 |
yes | yes |
| Instagram Feed (4:3) | 1112:834 |
yes (approx) | 1104:832 |
Image ratios
gen4_image / gen4_image_turbo: 1024:1024, 1080:1080, 1168:880, 1360:768, 1440:1080, 1080:1440, 1808:768, 1920:1080, 1080:1920, 2112:912, 1280:720, 720:1280, 720:720, 960:720, 720:960, 1680:720
gemini_2.5_flash: 1344:768, 768:1344, 1024:1024, 1184:864, 864:1184, 1536:672, 832:1248, 1248:832, 896:1152, 1152:896
Output Conventions
- Files are saved to
--output-dir(default:output/). - Filenames use the pattern:
YYYY-MM-DD-HH-MM-SS-<name>.ext - Scripts print the local file path to stdout on success.
- Scripts print structured JSON lines (
{"event": "runway_task", ...}and{"event": "runway_result", ...}) to stdout for machine consumption. - Status/progress messages go to stderr.
- Do NOT read generated media files back into the conversation — just report the file paths to the user.
Local File Handling
All scripts accept local file paths for image, video, and audio inputs. Local files are automatically uploaded via the Runway uploads API (ephemeral, valid for 24h) before being used in generation requests.
Error Handling
| Error | Meaning | Action |
|---|---|---|
| 429 / rate limit | Too many requests | Wait and retry |
| 402 / insufficient credits | Not enough credits | User must top up at runway.com |
| SAFETY.INPUT.IMAGE | Input image flagged | Revise the input image |
| SAFETY.OUTPUT | Generated content flagged | Revise the prompt |
| Task FAILED | Generation failed | Check the failure message, adjust inputs |
Prompt Tips for Product Ad Videos
- Describe camera movement explicitly: "slow dolly in", "smooth orbit around product", "camera pulls back to reveal"
- Specify lighting: "soft studio lighting", "golden hour warm light", "dramatic side light"
- Keep the product description concrete: material, color, size cues
- For seedance2, the reference image carries the visual identity — the prompt should describe motion and scene, not the product itself
- Shorter prompts (1-2 sentences) often produce better results than long descriptions