Runway API Skill#

Generate AI videos, images, and audio using Runway's API. Features Gen-4.5 — Runway's latest and most capable model — supporting both text-to-video and image-to-video generation, plus Gen-4 variants and third-party models from Google (Veo) and ElevenLabs.

Setup#

1. Get your API key from dev.runwayml.com
2. Store it as RUNWAYML_API_SECRET in your environment
3. Install the Node.js SDK: npm install @runwayml/sdk

Quick Start#

Text-to-Video (gen4.5)#

javascript

import RunwayML from "@runwayml/sdk";

const client = new RunwayML(); // reads RUNWAYML_API_SECRET automatically

const task = await client.textToVideo.create({
  model: "gen4.5",
  promptText: "A steaming bowl of noodles in a busy hawker centre, warm light, slow camera push-in",
  duration: 5,
  ratio: "1280:720"
}).waitForTaskOutput();

console.log("Video URL:", task.output[0]);

Image-to-Video (gen4.5)#

javascript

import RunwayML from "@runwayml/sdk";
import fs from "fs";

const client = new RunwayML();

const imageData = fs.readFileSync("product.jpg");
const promptImage = `data:image/jpeg;base64,${imageData.toString("base64")}`;

const task = await client.imageToVideo.create({
  model: "gen4.5",
  promptImage,
  promptText: "Slow dolly-in toward the product jar, warm side lighting, sauce shimmer visible through glass",
  duration: 5,
  ratio: "1280:720"
}).waitForTaskOutput();

console.log("Video URL:", task.output[0]);

cURL (direct API)#

bash

# Text-to-video
curl -X POST "https://api.dev.runwayml.com/v1/image_to_video" \
  -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
  -H "X-Runway-Version: 2024-11-06" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gen4.5",
    "promptText": "A serene mountain landscape at sunset",
    "ratio": "1280:720",
    "duration": 5
  }'

Available Models#

Video Generation#

ModelInputCredits/secNotes**gen4.5** ⭐Text or Image12Newest & recommendedgen4_turboImage only5Fast I2V iterationveo3.1Text or Image40Google Veo — includes audioveo3.1_fastText or Image15Veo — audio, cheapergen4_alephVideo + Text/Image15Video-to-video transformationact_twoImage or Video5Character performance/motion

Image Generation#

ModelCreditsNotesgen4_image5–8/imageHigh quality, supports style referencesgen4_image_turbo2/imageFast iteration (requires reference image)

Audio (ElevenLabs via Runway)#

ModelOutputCreditseleven_multilingual_v2Text → Speech1/50 charseleven_text_to_sound_v2Text → Sound FX1/6 seceleven_voice_dubbingAudio → Dubbed1/2 sec

Valid Ratios#

RatioFormat1280:72016:9 landscape (standard)720:12809:16 portrait (Reels/Stories)1584:67221:9 ultra-wide1104:8324:3832:11043:4960:960Square

Duration#

• gen4.5: 2–10 seconds
• gen4_turbo: 5 or 10 seconds

Task Polling#

All operations are async. The SDK's .waitForTaskOutput() handles polling automatically (10 min timeout).

Statuses: PENDING → THROTTLED → RUNNING → SUCCEEDED / FAILED

Manual poll:

bash

curl "https://api.dev.runwayml.com/v1/tasks/{task_id}" \
  -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
  -H "X-Runway-Version: 2024-11-06"

Prompting Tips#

• Describe single scenes (5–10 sec clips)
• Use clear physical descriptions, not abstract concepts
• For camera movement: "slow dolly-in", "tracking shot", "push toward subject"
• Avoid negative phrasing — "no blur" produces unpredictable results
• Keep prompts grounded and physically plausible

Official Docs#

• Runway API Documentation
• Model Guide
• Developer Portal