1. Copy the source/ directory into your project, for example at src/runway/.

2. In your tsconfig.json ensure moduleResolution supports path aliases and modern module output:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "outDir": "dist",
    "rootDir": "src"
  }
}

3. If you use path aliases, add the source root:

{
  "compilerOptions": {
    "paths": {
      "@runway/*": ["src/runway/*"]
    }
  }
}

4. Set your API key as an environment variable before running the server:

export RUNWAYML_API_SECRET=your_api_key_here

5. Import the client from wherever you placed the source:

import RunwayML from './runway/index';

Public API

RunwayML

import RunwayML, { type ClientOptions } from './runway/index';

const client = new RunwayML({
  apiKey: string;          // defaults to process.env['RUNWAYML_API_SECRET']
  maxRetries?: number;     // default 2
  timeout?: number;        // milliseconds, default 60_000
  baseURL?: string;
});

The main client. Instantiate once per process. All resource namespaces (client.imageToVideo, client.tasks, client.avatars, etc.) are properties on this instance. Pass ClientOptions to override retry/timeout behavior globally.

APIError

import { APIError, BadRequestError, NotFoundError, RateLimitError } from './runway/index';

try {
  await client.imageToVideo.create(params);
} catch (err) {
  if (err instanceof APIError) {
    err.status;   // HTTP status code
    err.name;     // e.g. "BadRequestError"
    err.headers;  // response headers
  }
}

Base class for all HTTP error responses. Subclass by status code: BadRequestError (400), AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), UnprocessableEntityError (422), RateLimitError (429), InternalServerError (>=500), APIConnectionError (network).

toFile

import { toFile, type Uploadable } from './runway/index';
import fs from 'fs';

const uploadable: Uploadable = await toFile(fs.createReadStream('./audio.mp3'), 'audio.mp3', {
  type: 'audio/mpeg',
});

Converts a ReadableStream, Buffer, Blob, or file path into an Uploadable that the SDK can attach as multipart form data. Use this whenever a resource parameter accepts a file input.

TaskFailedError / TaskTimedOutError

import { TaskFailedError, TaskTimedOutError, type WaitForTaskOutputOptions } from './runway/index';

Thrown by the polling helpers in lib/polling.ts when an async task ends in a failure state or exceeds the polling timeout. Use these to distinguish terminal failures from transient errors.

Working examples

Scenario - Generate a video from an image

Create a generation task and poll until the output URL is available.

import RunwayML, { TaskFailedError, TaskTimedOutError } from './runway/index';

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

async function generateVideo() {
  const task = await client.imageToVideo
    .create({
      model: 'gen4_turbo',
      promptImage: 'https://example.com/assets/bunny.jpg',
      ratio: '1280:720',
      promptText: 'The bunny is eating a carrot',
    })
    .waitForTaskOutput({ pollingIntervalMs: 5000, timeoutMs: 300_000 });

  console.log('Output URL:', task.output);
}

generateVideo().catch((err) => {
  if (err instanceof TaskFailedError) {
    console.error('Task failed:', err.message);
  } else if (err instanceof TaskTimedOutError) {
    console.error('Task timed out');
  } else {
    throw err;
  }
});

Scenario - Text-to-image with error handling

Submit a text-to-image request and handle HTTP errors by status code.

import RunwayML, { APIError, RateLimitError, AuthenticationError } from './runway/index';
import type { TextToImageCreateParams } from './runway/resources/index';

const client = new RunwayML();

async function makeImage(prompt: string) {
  const params: TextToImageCreateParams = {
    promptText: prompt,
    model: 'gen4_image',
    ratio: '1024:1024',
  };

  try {
    const result = await client.textToImage.create(params);
    console.log('Task ID:', result.id);
    return result;
  } catch (err) {
    if (err instanceof AuthenticationError) {
      console.error('Invalid API key');
    } else if (err instanceof RateLimitError) {
      console.error('Rate limited - back off and retry');
    } else if (err instanceof APIError) {
      console.error(`API error ${err.status}: ${err.name}`);
    } else {
      throw err;
    }
  }
}

Scenario - List avatars with cursor-based pagination

Page through all avatars in the organization using the cursor page helper.

import RunwayML from './runway/index';
import type { AvatarListResponsesCursorPage } from './runway/resources/index';

const client = new RunwayML();

async function listAllAvatars() {
  const page: AvatarListResponsesCursorPage = await client.avatars.list({ limit: 20 });

  for await (const avatar of page) {
    console.log(avatar.id, avatar.name);
  }
}

listAllAvatars();

File walkthrough

• source/client.ts - Defines RunwayML class and ClientOptions; wires all resource sub-clients as properties; handles retry, timeout, auth header injection.
• source/index.ts - Single entry point re-exporting every public symbol; this is the file your code should import from.
• source/resources/ - Each file wraps one REST resource (ImageToVideo, Tasks, Avatars, Documents, SoundEffect, etc.) with typed create/retrieve/list/update methods.
• source/core/api-promise.ts - APIPromise<T> extends native Promise with .withResponse() and .asResponse() to access raw headers/status alongside data.
• source/core/pagination.ts - CursorPage and PagePromise implementations for iterating multi-page results.
• source/core/error.ts - All typed HTTP error classes; source of truth for error hierarchy.
• source/core/uploads.ts - toFile helper and Uploadable type for multipart uploads.
• source/lib/polling.ts - waitForTaskOutput and waitForWorkflowInvocation with configurable polling interval and timeout; exports TaskFailedError, TaskTimedOutError, WorkflowInvocationFailedError, WorkflowInvocationTimedOutError.
• source/internal/ - Platform detection, header merging, query string serialization, fetch shims; not intended to be imported directly.
• source/version.ts - Exports VERSION string ("3.20.0").

Common pitfalls and fixes

• Missing RUNWAYML_API_SECRET env var - The constructor silently accepts undefined but every request will return 401; always validate process.env.RUNWAYML_API_SECRET at startup.
• Node.js < 18 has no global fetch - Install node-fetch and assign global.fetch = require('node-fetch') before importing the client, or upgrade to Node 18+.
• ESM/CJS interop errors with moduleResolution - Set "moduleResolution": "NodeNext" and "module": "NodeNext" together; mixing "CommonJS" module with "bundler" resolution breaks internal relative imports.
• waitForTaskOutput never resolves in tests - The polling helper uses real setTimeout; in Jest use jest.useFakeTimers() and advance timers manually, or pass a very short timeoutMs to force TaskTimedOutError.
• toFile with fs.createReadStream fails in edge runtimes - Edge/Cloudflare Workers have no fs module; use new Blob([buffer]) passed directly to toFile instead.
• Deprecated shim imports - source/api-promise.ts, source/pagination.ts, and source/error.ts are marked @deprecated; import from source/core/* or source/index.ts to avoid warnings.

Vibe-coding prompt template

I have the RunwayML TypeScript SDK source checked into my project at `src/runway/`
(upstream package: @runwayml/sdk@3.20.0). The integration guide is in `USAGE.md`.

Please help me integrate this SDK into my existing Node.js/TypeScript project step by step:

1. Read `USAGE.md` and `src/runway/index.ts` to understand every public export.
2. Instantiate the `RunwayML` client using `process.env.RUNWAYML_API_SECRET`.
3. Add a function that calls `client.imageToVideo.create(...)` with the params I describe,
   then uses `.waitForTaskOutput()` to poll until the video URL is ready.
4. Add typed error handling using `TaskFailedError`, `TaskTimedOutError`, and `APIError`
   from `src/runway/index.ts`.
5. Show me where to place environment variables and how to update `tsconfig.json`
   if needed.
6. All imports must reference `src/runway/index` or `src/runway/resources/index`;
   do not use the npm package name `@runwayml/sdk` directly.

License and credit

The upstream package is @runwayml/sdk by Runway AI, Inc. The source is generated by Stainless from the RunwayML OpenAPI spec. See source/LICENSE if present for the full license text. REST API documentation: docs.dev.runwayml.com. npm: https://npmjs.org/package/@runwayml/sdk.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Twilio Video JavaScript SDK for Web Apps

Automation, Utilities & Developer Tools

Free