Runway Free code examples in Python and JavaScript

The package is scoped. The secret lives in RUNWAYML_API_SECRET and the client picks it up on its own.

npm install @runwayml/sdk

export RUNWAYML_API_SECRET="key_your-secret"

promptImage is a URL the API fetches. ratio is pixel dimensions with a colon — '1280:720' — and not an aspect ratio string, which is the mistake the error message does not quite explain.

import RunwayML from "@runwayml/sdk";

const client = new RunwayML();

const task = await client.imageToVideo.create({
  model: "gen4.5",
  promptImage: "https://example.com/assets/microphone.jpg",
  promptText: "The camera slowly pushes in on the microphone",
  ratio: "1280:720",
  duration: 5,
});

console.log("submitted:", task.id);

waitForTaskOutput polls at the documented rate. Runway asks for no more than one check every five seconds per task, and a hand-written loop usually gets that wrong in one direction or the other.

import { TaskFailedError } from "@runwayml/sdk";

try {
  const result = await client.imageToVideo
    .create({
      model: "gen4.5",
      promptImage: "https://example.com/assets/microphone.jpg",
      promptText: "The camera slowly pushes in on the microphone",
      ratio: "1280:720",
      duration: 5,
    })
    .waitForTaskOutput();

  console.log(result.output[0]);
} catch (error) {
  if (error instanceof TaskFailedError) {
    // Usually moderation, or a source image the model rejected.
    console.error("generation failed:", error.taskDetails);
  } else {
    throw error;
  }
}

Rendering takes minutes and a request that waits will be killed by something in between. Submit, return the id, and let the client poll your own endpoint.

import express from "express";

const app = express();
app.use(express.json());

app.post("/videos", async (request, response) => {
  const task = await client.imageToVideo.create({
    model: "gen4.5",
    promptImage: request.body.imageUrl,
    promptText: request.body.prompt,
    ratio: "1280:720",
    duration: 5,
  });

  response.status(202).json({ taskId: task.id, status: "PENDING" });
});

app.get("/videos/:id", async (request, response) => {
  const task = await client.tasks.retrieve(request.params.id);

  response.json({
    status: task.status,     // PENDING | RUNNING | SUCCEEDED | FAILED
    url: task.status === "SUCCEEDED" ? task.output[0] : null,
  });
});

app.listen(3000);

The output URL is signed and short-lived. Stream it to disk or to object storage the moment the task succeeds — a stored URL is a broken video tomorrow.

import { createWriteStream } from "node:fs";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";

const result = await client.imageToVideo
  .create({
    model: "gen4.5",
    promptImage: "https://example.com/assets/microphone.jpg",
    promptText: "The camera slowly pushes in on the microphone",
    ratio: "1280:720",
    duration: 5,
  })
  .waitForTaskOutput();

const video = await fetch(result.output[0]);
if (!video.ok) throw new Error(`Download failed: ${video.status}`);

// Stream it: a ten-second clip is tens of megabytes.
await pipeline(Readable.fromWeb(video.body), createWriteStream("clip.mp4"));