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

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:

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 poll-based; webhook support is unconfirmed [VERIFY]
• 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