name: runway-gen4-api description: Use this skill whenever the user wants to generate video with the Runway API (Gen-4 Turbo, Gen-4.5, Gen-3 Alpha Turbo) from agent code. Triggers include any mention of "Runway", "Runway API", "image to video", "gen4-turbo", "gen4.5", "runwayml SDK", or asking an agent to render a clip from a still. Do not trigger for the runwayml.com consumer app, video editor sessions, or for short cinematic shots where Higgsfield is a better fit.

Run Runway Gen-4 cleanly

The Runway API is a separate product from the runwayml.com consumer app. Different keys, different billing, separate dashboard at dev.runwayml.com. Agents that confuse the two waste an hour trying to authenticate. The other thing agents get wrong: Runway's prompt grammar is closer to a shot list than to a text-to-image prompt. Concrete subject, concrete motion, concrete camera. This skill teaches the model lineup, task lifecycle, and prompt structure Runway actually rewards.

When to use Runway

Use Runway when the user wants:

• Image-to-video from a strong starting frame (the dominant API path)
• 5 or 10-second clips with good subject coherence
• Realistic motion on top of an existing still (product, character, environment moves)
• Text-to-video on Gen-4.5 when no starting image exists

Do not reach for Runway when:

• A specific camera move (push-in, orbit, dolly-zoom) is the hero of the shot. Use Higgsfield, its preset library is the product
• The user wants longer than 10 seconds in one call. Chain clips or use Veo via Runway's veo3 route
• The user wants free or near-free iteration. Runway is credit-priced
• The user wants video-to-video restyling. Use gen4-aleph, a different endpoint

Install & REST Setup

For direct HTTP requests (REST), use the exact base URL: https://api.runwayml.com/v1. You MUST include the required X-Runway-Version header (e.g., X-Runway-Version: 2024-11-06) on all API requests.

Python SDK (current 4.14.0) and Node SDK (current 3.17.0):

pip install runwayml             # Python 3.9+
npm install @runwayml/sdk        # Node 18+
export RUNWAYML_API_SECRET=key_...

Official MCP server at github.com/runwayml/runway-api-mcp-server. Not on npm yet, clone + build:

git clone https://github.com/runwayml/runway-api-mcp-server
cd runway-api-mcp-server && npm install && npm run build

Point your agent's MCP config at the built index.js with RUNWAYML_API_SECRET in env. Tools: runway_generateVideo, runway_generateImage, runway_upscaleVideo, runway_editVideo, runway_getTask, runway_cancelTask, runway_getOrg.

Model selection

| Model | Best for | Duration | Cost (credits/sec) | Notes | |-------|----------|----------|--------------------|-------| | gen4-turbo | Default image-to-video. Fast, cheap, good motion coherence | 5 or 10s | 5 | Start here for iteration | | gen4.5 | Higher quality, also supports text-to-video without promptImage | 5 or 10s | 12 | Use after locking direction on Turbo | | gen4-aleph | Video-to-video restyling, not image-to-video | varies | varies | Different endpoint, not interchangeable | | veo3 / veo3.1 | Routed via Runway, premium quality | varies | 40 | Expensive, save for finals |

Gen-3 Alpha models (including gen3a-turbo) are no longer listed in the current Runway API docs. If you have old code referencing them, migrate to gen4-turbo.

Default playbook: iterate on gen4-turbo until composition and motion look right, then re-render the keeper on gen4.5 at the same prompt + seed.

Task lifecycle (the part agents botch)

Every generation is a task. Statuses: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED. Output URLs live 24 to 48 hours, then evaporate. Download immediately, do not hand the raw URL to the user as a deliverable.

Python polling pattern:

import os, time
from runwayml import RunwayML

client = RunwayML(api_key=os.environ["RUNWAYML_API_SECRET"])

task = client.image_to_video.create(
    model="gen4-turbo",
    prompt_image="https://your-cdn.example/frame.jpg",
    prompt_text="The cyclist pedals away as the camera dollies back, dusk light",
    ratio="1280:720",
    duration=5,
)

# Use the SDK helper, do not hand-roll the loop
result = client.tasks.wait_for_task_output(task.id, timeout=600)
output_url = result.output[0]  # download this immediately

Node:

import RunwayML from "@runwayml/sdk";

const client = new RunwayML({ apiKey: process.env.RUNWAYML_API_SECRET });

const task = await client.imageToVideo.create({
  model: "gen4-turbo",
  promptImage: "https://your-cdn.example/frame.jpg",
  promptText: "The cyclist pedals away as the camera dollies back, dusk light",
  ratio: "1280:720",
  duration: 5,
});

const result = await client.tasks.waitForTaskOutput(task.id, { timeout: 600_000 });
const outputUrl = result.output[0];

If you must hand-roll polling, sleep 5 seconds between retrieves. Faster polling gets rate-limited and does not return faster.

Prompt structure Runway actually rewards

Three slots, in this order:

1. Subject and action. What is in frame, what it does
2. Camera. Explicit camera move, or "static camera"
3. Light and atmosphere. Time of day, lens feel, weather

Bad: a guy walking Bad: cinematic shot of a person Good: man in a navy overcoat walks left to right across a cobblestone street, camera tracks alongside at waist height, overcast afternoon, shallow depth of field

If the user gives a vague request, ask one question before generating: is there a starting frame, or does this need text-to-video on gen4.5? Then generate. Do not stack three clarifying questions.

Aspect ratio is locked at task creation. Supported on gen4-turbo:

| Ratio | Use case | |-------|----------| | 1280:720 | Standard landscape, YouTube, web | | 720:1280 | Phone vertical, Reels, TikTok | | 1584:672 | Ultra-wide cinematic | | 1104:832 | 4:3-ish landscape | | 832:1104 | 4:3-ish portrait | | 960:960 | Square, Instagram feed |

Duration is 5 or 10. There is no in-between. A 10-second clip costs exactly 2x a 5-second clip.

Cost gotchas

• A gen4-turbo 5-second clip is 25 credits; the same prompt on gen4.5 is 60 credits. Always iterate on Turbo
• Failed tasks (FAILED status) typically do not consume credits, but CANCELED mid-run may. Cancel early if you cancel at all
• The Runway API uses a separate credit pool from the consumer app subscription. Topping up your runwayml.com Plus plan does not fund API calls
• Commercial use is allowed; on every plan except Enterprise, Runway retains a license to train on your outputs. If the user is generating proprietary brand work, flag this

Live USD-per-second math and current model availability: scopeful.org/tools/runway.

What to deliver to the user

For each successful generation, return:

1. The downloaded local file path (not the expiring URL)
2. One line of intent ("Used gen4-turbo at 720p for cheap iteration, switch to gen4.5 for the final")
3. The credit cost (model rate x duration)
4. A suggested next move (re-roll with a seed, upscale, or chain a second clip)

What NOT to do

• Do not paste output URLs into chat as the deliverable. They expire. Download first
• Do not auto-retry FAILED tasks more than once. Read the error, adjust the prompt
• Do not retry content-filter rejections with the same prompt. Rephrase
• Do not use gen4.5 for first iteration. Burn 25 credits on gen4-turbo before burning 60 on gen4.5
• Do not promise webhook delivery. The dev API is strictly poll-based; use the async polling loop via GET /v1/tasks/{id} as the standard approach.
• Do not skip the "Powered by Runway" attribution in user-facing apps. It is required by API terms

Useful follow-ups

• For a tighter cinematic shot (push-in, orbit, dolly-zoom), hand off to the higgsfield-mcp skill. Its preset library is sharper than Runway's freeform camera prompts
• For voiceover, chain ElevenLabs. eleven_multilingual_v2 is also accessible via Runway's audio endpoints if you want one billing surface
• For longer sequences, render multiple 10-second clips with overlapping last/first frames and stitch in post
• For text-to-image starting frames, use gen4-image in the same SDK, or hand off to Midjourney via the midjourney-v7-prompts skill