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.

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:

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:

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

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

Audio models

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

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

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

Setup

The user must set their Runway API key:

export RUNWAYML_API_SECRET="your-api-key"

All scripts accept --api-key as an alternative.